Sprite 1984

home *** CD-ROM | disk | FTP | other *** search

/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / tcl / Tcl.man < prev next >

Wrap

Text File | 1992-11-01 | 170.7 KB | 3,433 lines

Tcl C Library Procedures Tcl _________________________________________________________________ NNAAMMEE Tcl - overview of tool command language facilities _________________________________________________________________ IINNTTRROODDUUCCTTIIOONN Tcl stands for ``tool command language'' and is pronounced ``tickle.'' It is actually two things: a language and a library. First, Tcl is a simple textual language, intended primarily for issuing commands to interactive programs such as text editors, debuggers, illustrators, and shells. It has a simple syntax and is also programmable, so Tcl users can write command procedures to provide more powerful com- mands than those in the built-in set. Second, Tcl is a library package that can be embedded in application programs. The Tcl library consists of a parser for the Tcl language, routines to implement the Tcl built-in commands, and procedures that allow each application to extend Tcl with additional commands specific to that appli- cation. The application program generates Tcl commands and passes them to the Tcl parser for execution. Commands may be generated by reading characters from an input source, or by associating command strings with elements of the application's user interface, such as menu entries, buttons, or keystrokes. When the Tcl library receives commands it parses them into component fields and executes built-in com- mands directly. For commands implemented by the applica- tion, Tcl calls back to the application to execute the com- mands. In many cases commands will invoke recursive invoca- tions of the Tcl interpreter by passing in additional strings to execute (procedures, looping commands, and condi- tional commands all work in this way). An application program gains three advantages by using Tcl for its command language. First, Tcl provides a standard syntax: once users know Tcl, they will be able to issue commands easily to any Tcl-based application. Second, Tcl provides programmability. All a Tcl application needs to do is to implement a few application-specific low-level com- mands. Tcl provides many utility commands plus a general programming interface for building up complex command pro- cedures. By using Tcl, applications need not re-implement these features. Third, Tcl can be used as a common language | for communicating between applications. Inter-application | communication is not built into the Tcl core described here, | but various add-on libraries, such as the Tk toolkit, allow | applications to issue commands to each other. This makes it | possible for applications to work together in much more | powerful ways than was previously possible. Sprite v1.0 1 Tcl C Library Procedures Tcl This manual page focuses primarily on the Tcl language. It describes the language syntax and the built-in commands that will be available in any application based on Tcl. The individual library procedures are described in more detail in separate manual pages, one per procedure. IINNTTEERRPPRREETTEERRSS The central data structure in Tcl is an interpreter (C type ``Tcl_Interp''). An interpreter consists of a set of com- mand bindings, a set of variable values, and a few other miscellaneous pieces of state. Each Tcl command is inter- preted in the context of a particular interpreter. Some Tcl-based applications will maintain multiple interpreters simultaneously, each associated with a different widget or portion of the application. Interpreters are relatively lightweight structures. They can be created and deleted quickly, so application programmers should feel free to use multiple interpreters if that simplifies the application. Eventually Tcl will provide a mechanism for sending Tcl com- mands and results back and forth between interpreters, even if the interpreters are managed by different processes. DDAATTAA TTYYPPEESS Tcl supports only one type of data: strings. All commands, all arguments to commands, all command results, and all variable values are strings. Where commands require numeric arguments or return numeric results, the arguments and results are passed as strings. Many commands expect their string arguments to have certain formats, but this interpre- tation is up to the individual commands. For example, argu- ments often contain Tcl command strings, which may get exe- cuted as part of the commands. The easiest way to under- stand the Tcl interpreter is to remember that everything is just an operation on a string. In many cases Tcl constructs will look similar to more structured constructs from other languages. However, the Tcl constructs are not structured at all; they are just strings of characters, and this gives them a different behavior than the structures they may look like. Although the exact interpretation of a Tcl string depends on who is doing the interpretation, there are three common forms that strings take: commands, expressions, and lists. The major sections below discuss these three forms in more detail. BBAASSIICC CCOOMMMMAANNDD SSYYNNTTAAXX The Tcl language has syntactic similarities to both the Unix shells and Lisp. However, the interpretation of commands is Sprite v1.0 2 Tcl C Library Procedures Tcl different in Tcl than in either of those other two systems. A Tcl command string consists of one or more commands separated by newline characters or semi-colons. Each com- mand consists of a collection of fields separated by white space (spaces or tabs). The first field must be the name of a command, and the additional fields, if any, are arguments that will be passed to that command. For example, the com- mand sseett aa 2222 has three fields: the first, sseett, is the name of a Tcl com- mand, and the last two, aa and 2222, will be passed as argu- ments to the sseett command. The command name may refer either to a built-in Tcl command, an application-specific command bound in with the library procedure TTccll__CCrreeaatteeCCoommmmaanndd, or a command procedure defined with the pprroocc built-in command. Arguments are passed literally as text strings. Individual commands may interpret those strings in any fashion they wish. The sseett command, for example, will treat its first argument as the name of a variable and its second argument as a string value to assign to that variable. For other commands arguments may be interpreted as integers, lists, file names, or Tcl commands. Command names should normally be typed completely (e.g. no | abbreviations). However, if the Tcl interpreter cannot | locate a command it invokes a special command named uunnkknnoowwnn | which attempts to find or create the command. For example, | at many sites uunnkknnoowwnn will search through library direc- | tories for the desired command and create it as a Tcl pro- | cedure if it is found. The uunnkknnoowwnn command often provides | automatic completion of abbreviated commands, but usually | only for commands that were typed interactively. It's prob- | ably a bad idea to use abbreviations in command scripts and | other forms that will be re-used over time: changes to the | command set may cause abbreviations to become ambiguous, | resulting in scripts that no longer work. CCOOMMMMEENNTTSS If the first non-blank character in a command is ##, then everything from the ## up through the next newline character is treated as a comment and ignored. When comments are embedded inside nested commands (e.g. fields enclosed in braces) they must have properly-matched braces (this is necessary because when Tcl parses the top-level command it doesn't yet know that the nested field will be used as a command so it cannot process the nested comment character as a comment). Sprite v1.0 3 Tcl C Library Procedures Tcl GGRROOUUPPIINNGG AARRGGUUMMEENNTTSS WWIITTHH DDOOUUBBLLEE--QQUUOOTTEESS Normally each argument field ends at the next white space, but double-quotes may be used to create arguments with embedded space. If an argument field begins with a double- quote, then the argument isn't terminated by white space (including newlines) or a semi-colon (see below for informa- tion on semi-colons); instead it ends at the next double- quote character. The double-quotes are not included in the resulting argument. For example, the command sseett aa ""TThhiiss iiss aa ssiinnggllee aarrgguummeenntt"" will pass two arguments to sseett: aa and TThhiiss iiss aa ssiinnggllee aarrgguummeenntt. Within double-quotes, command substitutions, variable substitutions, and backslash substitutions still occur, as described below. If the first character of a com- mand field is not a quote, then quotes receive no special interpretation in the parsing of that field. GGRROOUUPPIINNGG AARRGGUUMMEENNTTSS WWIITTHH BBRRAACCEESS Curly braces may also be used for grouping arguments. They are similar to quotes except for two differences. First, they nest; this makes them easier to use for complicated arguments like nested Tcl command strings. Second, the sub- stitutions described below for commands, variables, and backslashes do _n_o_t occur in arguments enclosed in braces, so braces can be used to prevent substitutions where they are undesirable. If an argument field begins with a left brace, then the argument ends at the matching right brace. Tcl will strip off the outermost layer of braces and pass the information between the braces to the command without any further modification. For example, in the command sseett aa {{xxyyzz aa {{bb cc dd}}}} the sseett command will receive two arguments: aa and xxyyzz aa {{bb cc dd}}. When braces or quotes are in effect, the matching brace or quote need not be on the same line as the starting quote or brace; in this case the newline will be included in the argument field along with any other characters up to the matching brace or quote. For example, the eevvaall command takes one argument, which is a command string; eevvaall invokes the Tcl interpreter to execute the command string. The com- mand eevvaall {{ sseett aa 2222 sseett bb 3333 }} will assign the value 2222 to aa and 3333 to bb. Sprite v1.0 4 Tcl C Library Procedures Tcl If the first character of a command field is not a left brace, then neither left nor right braces in the field will be treated specially (except as part of variable substitu- tion; see below). CCOOMMMMAANNDD SSUUBBSSTTIITTUUTTIIOONN WWIITTHH BBRRAACCKKEETTSS If an open bracket occurs in a field of a command, then com- mand substitution occurs (except for fields enclosed in braces). All of the text up to the matching close bracket is treated as a Tcl command and executed immediately. Then the result of that command is substituted for the bracketed text. For example, consider the command sseett aa [[sseett bb]] When the sseett command has only a single argument, it is the name of a variable and sseett returns the contents of that variable. In this case, if variable bb has the value ffoooo, then the command above is equivalent to the command sseett aa ffoooo Brackets can be used in more complex ways. For example, if the variable bb has the value ffoooo and the variable cc has the value ggoorrpp, then the command sseett aa xxyyzz[[sseett bb]]..[[sseett cc]] is equivalent to the command sseett aa xxyyzzffoooo..ggoorrpp A bracketed command may contain multiple commands separated | by newlines or semi-colons in the usual fashion. In this | case the value of the last command is used for substitution. | For example, the command | sseett aa xx[[sseett bb 2222 | eexxpprr $$bb++22]]xx | is equivalent to the command | sseett aa xx2244xx | If a field is enclosed in braces then the brackets and the characters between them are not interpreted specially; they are passed through to the argument verbatim. VVAARRIIAABBLLEE SSUUBBSSTTIITTUUTTIIOONN WWIITTHH $$ The dollar sign ($$) may be used as a special shorthand form for substituting variable values. If $$ appears in an argu- ment that isn't enclosed in braces then variable substitu- tion will occur. The characters after the $$, up to the first character that isn't a number, letter, or underscore, are taken as a variable name and the string value of that variable is substituted for the name. For example, if | Sprite v1.0 5 Tcl C Library Procedures Tcl variable ffoooo has the value tteesstt, then the command | sseett aa $$ffoooo..cc | is equivalent to the command | sseett aa tteesstt..cc | There are two special forms for variable substitution. If | the next character after the name of the variable is an open | parenthesis, then the variable is assumed to be an array | name, and all of the characters between the open parenthesis | and the next close parenthesis are taken as an index into | the array. Command substitutions and variable substitutions | are performed on the information between the parentheses | before it is used as an index. For example, if the variable | xx is an array with one element named ffiirrsstt and value 8877 and | another element named 1144 and value mmoorree, then the command | sseett aa xxyyzz$$xx((ffiirrsstt))zzyyxx | is equivalent to the command | sseett aa xxyyzz8877zzyyxx | If the variable iinnddeexx has the value 1144, then the command | sseett aa xxyyzz$$xx(($$iinnddeexx))zzyyxx | is equivalent to the command | sseett aa xxyyzzmmoorreezzyyxx | For more information on arrays, see VARIABLES AND ARRAYS | below. | The second special form for variables occurs when the dollar | sign is followed by an open curly brace. In this case the | variable name consists of all the characters up to the next | curly brace. Array references are not possible in this | form: the name between braces is assumed to refer to a | scalar variable. For example, if variable ffoooo has the value | tteesstt, then the command | sseett aa aabbcc$${{ffoooo}}bbaarr | is equivalent to the command | sseett aa aabbcctteessttbbaarr | Variable substitution does not occur in arguments that are enclosed in braces: the dollar sign and variable name are passed through to the argument verbatim. The dollar sign abbreviation is simply a shorthand form. $$aa is completely equivalent to [[sseett aa]]; it is provided as a convenience to reduce typing. Sprite v1.0 6 Tcl C Library Procedures Tcl SSEEPPAARRAATTIINNGG CCOOMMMMAANNDDSS WWIITTHH SSEEMMII--CCOOLLOONNSS Normally, each command occupies one line (the command is terminated by a newline character). However, semi-colon (``;'') is treated as a command separator character; multi- ple commands may be placed on one line by separating them with a semi-colon. Semi-colons are not treated as command separators if they appear within curly braces or double- quotes. BBAACCKKSSLLAASSHH SSUUBBSSTTIITTUUTTIIOONN Backslashes may be used to insert non-printing characters into command fields and also to insert special characters like braces and brackets into fields without them being interpreted specially as described above. The backslash sequences understood by the Tcl interpreter are listed below. In each case, the backslash sequence is replaced by the given character: \\bb Backspace (0x8). \\ff Form feed (0xc). \\nn Newline (0xa). \\rr Carriage-return (0xd). \\tt Tab (0x9). \\vv Vertical tab (0xb). \\{{ Left brace (``{''). \\}} Right brace (``}''). \\[[ Open bracket (``[''). \\]] Close bracket (``]''). \\$$ Dollar sign (``$''). \\<<ssppaaccee>> Space (`` ''): doesn't terminate argu- ment. \\;; Semi-colon: doesn't terminate command. \\"" Double-quote. \\<<nneewwlliinnee>> Nothing: this joins two lines together into a single line. This backslash feature is unique in that it will be applied even when the sequence occurs Sprite v1.0 7 Tcl C Library Procedures Tcl within braces. \\\\ Backslash (``\''). \\_d_d_d The digits _d_d_d (one, two, or three of them) give the octal value of the char- acter. Null characters may not be embedded in command fields; if _d_d_d is zero then the backslash sequence is ignored (i.e. it maps to an empty string). For example, in the command sseett aa \\{{xx\\[[\\ yyzz\\114411 the second argument to sseett will be ``{{xx[[ yyzzaa''. If a backslash is followed by something other than one of the options described above, then the backslash is transmit- ted to the argument field without any special processing, and the Tcl scanner continues normal processing with the next character. For example, in the command sseett \\**aa \\\\\\{{ffoooo The first argument to sseett will be \\**aa and the second argu- ment will be \\{{ffoooo. If an argument is enclosed in braces, then backslash sequences inside the argument are parsed but no substitution occurs (except for backslash-newline): the backslash sequence is passed through to the argument as is, without making any special interpretation of the characters in the backslash sequence. In particular, backslashed braces are not counted in locating the matching right brace that ter- minates the argument. For example, in the command sseett aa {{\\{{aabbcc}} the second argument to sseett will be \\{{aabbcc. This backslash mechanism is not sufficient to generate abso- lutely any argument structure; it only covers the most com- mon cases. To produce particularly complicated arguments it is probably easiest to use the ffoorrmmaatt command along with command substitution. CCOOMMMMAANNDD SSUUMMMMAARRYY [1] A command is just a string. [2] Within a string commands are separated by newlines or semi-colons (unless the newline or semi-colon is within braces or brackets or is backslashed). Sprite v1.0 8 Tcl C Library Procedures Tcl [3] A command consists of fields. The first field is the name of the command. The other fields are strings that are passed to that command as arguments. [4] Fields are normally separated by white space. [5] Double-quotes allow white space and semi-colons to appear within a single argument. Command substitution, variable substitution, and backslash substitution still occur inside quotes. [6] Braces defer interpretation of special characters. If a field begins with a left brace, then it consists of everything between the left brace and the matching right brace. The braces themselves are not included in the argument. No further processing is done on the information between the braces except that backslash- newline sequences are eliminated. [7] If a field doesn't begin with a brace then backslash, variable, and command substitution are done on the field. Only a single level of processing is done: the results of one substitution are not scanned again for further substitutions or any other special treatment. Substitution can occur on any field of a command, including the command name as well as the arguments. [8] If the first non-blank character of a command is a ##, everything from the ## up through the next newline is treated as a comment and ignored. EEXXPPRREESSSSIIOONNSS The second major interpretation applied to strings in Tcl is | as expressions. Several commands, such as eexxpprr, ffoorr, and | iiff, treat one or more of their arguments as expressions and | call the Tcl expression processors (TTccll__EExxpprrLLoonngg, | TTccll__EExxpprrBBoooolleeaann, etc.) to evaluate them. The operators per- | mitted in Tcl expressions are a subset of the operators per- | mitted in C expressions, and they have the same meaning and | precedence as the corresponding C operators. Expressions | almost always yield numeric results (integer or floating- | point values). For example, the expression | 88..22 ++ 66 | evaluates to 14.2. Tcl expressions differ from C expres- | sions in the way that operands are specified, and in that | Tcl expressions support non-numeric operands and string com- | parisons. | A Tcl expression consists of a combination of operands, | operators, and parentheses. White space may be used between | Sprite v1.0 9 Tcl C Library Procedures Tcl the operands and operators and parentheses; it is ignored by | the expression processor. Where possible, operands are | interpreted as integer values. Integer values may be speci- | fied in decimal (the normal case), in octal (if the first | character of the operand is 00), or in hexadecimal (if the | first two characters of the operand are 00xx). If an operand | does not have one of the integer formats given above, then | it is treated as a floating-point number if that is possi- | ble. Floating-point numbers may be specified in any of the | ways accepted by an ANSI-compliant C compiler (except that | the ``f'', ``F'', ``l'', and ``L'' suffixes will not be per- | mitted in most installations). For example, all of the fol- | lowing are valid floating-point numbers: 2.1, 3., 6e4, | 7.91e+16. If no numeric interpretation is possible, then an | operand is left as a string (and only a limited set of | operators may be applied to it). | Operands may be specified in any of the following ways: | [1] || As an numeric value, either integer or floating-point. | [2] || As a Tcl variable, using standard $$ notation. The | variable's value will be used as the operand. | [3] || As a string enclosed in double-quotes. The expression | parser will perform backslash, variable, and command | substitutions on the information between the quotes, | and use the resulting value as the operand | [4] || As a string enclosed in braces. The characters between | the open brace and matching close brace will be used as | the operand without any substitutions. | [5] || As a Tcl command enclosed in brackets. The command | will be executed and its result will be used as the | operand. | Where substitutions occur above (e.g. inside quoted | strings), they are performed by the expression processor. | However, an additional layer of substitution may already | have been performed by the command parser before the expres- | sion processor was called. As discussed below, it is usu- | ally best to enclose expressions in braces to prevent the | command parser from performing substitutions on the con- | tents. | For some examples of simple expressions, suppose the | Sprite v1.0 10 Tcl C Library Procedures Tcl variable aa has the value 3 and the variable bb has the value | 6. Then the expression on the left side of each of the | lines below will evaluate to the value on the right side of | the line: | 33..11 ++ $$aa 66..11 | 22 ++ ""$$aa..$$bb"" 55..66 | 44**[[lllleennggtthh ""66 22""]] 88 | {{wwoorrdd oonnee}} << ""wwoorrdd $$aa"" 00 | The valid operators are listed below, grouped in decreasing | order of precedence: | -- ~~ !! || Unary minus, bit-wise NOT, logical NOT. | None of these operands may be applied to | string operands, and bit-wise NOT may be | applied only to integers. | ** // %% || Multiply, divide, remainder. None of | these operands may be applied to string | operands, and remainder may be applied | only to integers. | ++ -- || Add and subtract. Valid for any numeric | operands. | <<<< >>>> || Left and right shift. Valid for integer | operands only. | << >> <<== >>== || Boolean less, greater, less than or | equal, and greater than or equal. Each | operator produces 1 if the condition is | true, 0 otherwise. These operators may | be applied to strings as well as numeric | operands, in which case string com- | parison is used. | ==== !!== || Boolean equal and not equal. Each | operator produces a zero/one result. | Valid for all operand types. | && || Bit-wise AND. Valid for integer | operands only. | ^^ || Sprite v1.0 11 Tcl C Library Procedures Tcl Bit-wise exclusive OR. Valid for | integer operands only. | || || Bit-wise OR. Valid for integer operands | only. | &&&& || Logical AND. Produces a 1 result if | both operands are non-zero, 0 otherwise. | Valid for numeric operands only | (integers or floating-point). | |||| || Logical OR. Produces a 0 result if both | operands are zero, 1 otherwise. Valid | for numeric operands only (integers or | floating-point). | _x??_y::_z || If-then-else, as in C. If _x evaluates | to non-zero, then the result is the | value of _y. Otherwise the result is the | value of _z. The _x operand must have a | numeric value. | See the C manual for more details on the results produced by | each operator. All of the binary operators group left-to- | right within the same precedence level. For example, the | expression | 44**22 << 77 | evaluates to 0. | The &&&&, ||||, and ??:: operators have ``lazy evaluation'', just | as in C, which means that operands are not evaluated if they | are not needed to determine the outcome. For example, in | $$vv ?? [[aa]] :: [[bb]] | only one of [[aa]] or [[bb]] will actually be evaluated, depending | on the value of $$vv. | All internal computations involving integers are done with | the C type _l_o_n_g, and all internal computations involving | floating-point are done with the C type _d_o_u_b_l_e. When con- | verting a string to floating-point, exponent overflow is | detected and results in a Tcl error. For conversion to | integer from string, detection of overflow depends on the | behavior of some routines in the local C library, so it | should be regarded as unreliable. In any case, overflow and | underflow are generally not detected reliably for intermedi- | ate results. | Sprite v1.0 12 Tcl C Library Procedures Tcl Conversion among internal representations for integer, | floating-point, and string operands is done automatically as | needed. For arithmetic computations, integers are used | until some floating-point number is introduced, after which | floating-point is used. For example, | 55 // 44 | yields the result 1, while | 55 // 44..00 | 55 // (( [[ssttrriinngg lleennggtthh ""aabbccdd""]] ++ 00..00 )) | both yield the result 1.25. | String values may be used as operands of the comparison | operators, although the expression evaluator tries to do | comparisons as integer or floating-point when it can. If | one of the operands of a comparison is a string and the | other has a numeric value, the numeric operand is converted | back to a string using the C _s_p_r_i_n_t_f format specifier %%dd for | integers and %%gg for floating-point values. For example, the | expressions | ""00xx0033"" >> ""22"" | ""00yy"" << ""00xx1122"" | both evaluate to 1. The first comparison is done using | integer comparison, and the second is done using string com- | parison after the second operand is converted to the string | ``18''. In general it is safest to enclose an expression in braces when entering it in a command: otherwise, if the expression contains any white space then the Tcl interpreter will split it among several arguments. For example, the command eexxpprr $$aa ++ $$bb results in three arguments being passed to eexxpprr: $$aa, ++, and $$bb. In addition, if the expression isn't in braces then the Tcl interpreter will perform variable and command substitu- tion immediately (it will happen in the command parser rather than in the expression parser). In many cases the expression is being passed to a command that will evaluate the expression later (or even many times if, for example, the expression is to be used to decide when to exit a loop). Usually the desired goal is to re-do the variable or command substitutions each time the expression is evaluated, rather than once and for all at the beginning. For example, the command ffoorr {{sseett ii 11}} $$ii<<==1100 {{iinnccrr ii}} {{......}}*** WRONG *** is probably intended to iterate over all values of ii from 1 to 10. After each iteration of the body of the loop, ffoorr will pass its second argument to the expression evaluator to Sprite v1.0 13 Tcl C Library Procedures Tcl see whether or not to continue processing. Unfortunately, in this case the value of ii in the second argument will be substituted once and for all when the ffoorr command is parsed. If ii was 0 before the ffoorr command was invoked then ffoorr's second argument will be 00<<==1100 which will always evaluate to 1, even though ii's value eventually becomes greater than 10. In the above case the loop will never terminate. Instead, the expression should be placed in braces: ffoorr {{sseett ii 11}} {{$$ii<<==1100}} {{iinnccrr ii}} {{......}}*** RIGHT *** This causes the substitution of ii's value to be delayed; it will be re-done each time the expression is evaluated, which is the desired result. LLIISSTTSS The third major way that strings are interpreted in Tcl is as lists. A list is just a string with a list-like struc- ture consisting of fields separated by white space. For example, the string AAll SSuuee AAnnnnee JJoohhnn is a list with four elements or fields. Lists have the same basic structure as command strings, except that a newline character in a list is treated as a field separator just like space or tab. Conventions for braces and quotes and backslashes are the same for lists as for commands. For example, the string aa bb\\ cc {{dd ee {{ff gg hh}}}} is a list with three elements: aa, bb cc, and dd ee {{ff gg hh}}. Whenever an element is extracted from a list, the same rules about braces and quotes and backslashes are applied as for commands. Thus in the example above when the third element is extracted from the list, the result is dd ee {{ff gg hh}} (when the field was extracted, all that happened was to strip off the outermost layer of braces). Command substitu- tion and variable substitution are never made on a list (at least, not by the list-processing commands; the list can always be passed to the Tcl interpreter for evaluation). The Tcl commands ccoonnccaatt, ffoorreeaacchh, llaappppeenndd, lliinnddeexx, lliinnsseerrtt, | lliisstt, lllleennggtthh, llrraannggee, llrreeppllaaccee, llsseeaarrcchh, and llssoorrtt allow | you to build lists, extract elements from them, search them, and perform other list-related functions. RREEGGUULLAARR EEXXPPRREESSSSIIOONNSS Tcl provides two commands that support string matching using | eeggrreepp-style regular expressions: rreeggeexxpp and rreeggssuubb. Regular | Sprite v1.0 14 Tcl C Library Procedures Tcl expressions are implemented using Henry Spencer's package, | and the description of regular expressions below is copied | verbatim from his manual entry. | A regular expression is zero or more _b_r_a_n_c_h_e_s, separated by | ``|''. It matches anything that matches one of the | branches. | A branch is zero or more _p_i_e_c_e_s, concatenated. It matches a | match for the first, followed by a match for the second, | etc. | A piece is an _a_t_o_m possibly followed by ``*'', ``+'', or | ``?''. An atom followed by ``*'' matches a sequence of 0 or | more matches of the atom. An atom followed by ``+'' matches | a sequence of 1 or more matches of the atom. An atom fol- | lowed by ``?'' matches a match of the atom, or the null | string. | An atom is a regular expression in parentheses (matching a | match for the regular expression), a _r_a_n_g_e (see below), | ``.'' (matching any single character), ``^'' (matching the | null string at the beginning of the input string), ``$'' | (matching the null string at the end of the input string), a | ``\'' followed by a single character (matching that charac- | ter), or a single character with no other significance | (matching that character). | A _r_a_n_g_e is a sequence of characters enclosed in ``[]''. It | normally matches any single character from the sequence. If | the sequence begins with ``^'', it matches any single char- | acter _n_o_t from the rest of the sequence. If two characters | in the sequence are separated by ``-'', this is shorthand | for the full list of ASCII characters between them (e.g. | ``[0-9]'' matches any decimal digit). To include a literal | ``]'' in the sequence, make it the first character (follow- | ing a possible ``^''). To include a literal ``-'', make it | the first or last character. | If a regular expression could match two different parts of a | string, it will match the one which begins earliest. If | both begin in the same place but match different lengths, or | match the same length in different ways, life gets messier, | as follows. | In general, the possibilities in a list of branches are con- | sidered in left-to-right order, the possibilities for ``*'', | ``+'', and ``?'' are considered longest-first, nested con- | structs are considered from the outermost in, and con- | catenated constructs are considered leftmost-first. The | match that will be chosen is the one that uses the earliest | possibility in the first choice that has to be made. If | Sprite v1.0 15 Tcl C Library Procedures Tcl there is more than one choice, the next will be made in the | same manner (earliest possibility) subject to the decision | on the first choice. And so forth. | For example, ``(ab|a)b*c'' could match ``abc'' in one of two | ways. The first choice is between ``ab'' and ``a''; since | ``ab'' is earlier, and does lead to a successful overall | match, it is chosen. Since the ``b'' is already spoken for, | the ``b*'' must match its last possibility-the empty | string-since it must respect the earlier choice. | In the particular case where no ``|''s are present and there | is only one ``*'', ``+'', or ``?'', the net effect is that | the longest possible match will be chosen. So ``ab*'', | presented with ``xabbbby'', will match ``abbbb''. Note that | if ``ab*'' is tried against ``xabyabbbz'', it will match | ``ab'' just after ``x'', due to the begins-earliest rule. | (In effect, the decision on where to start the match is the | first choice to be made, hence subsequent choices must | respect it even if this leads them to less-preferred alter- | natives.) CCOOMMMMAANNDD RREESSUULLTTSS Each command produces two results: a code and a string. The code indicates whether the command completed success- fully or not, and the string gives additional information. The valid codes are defined in tcl.h, and are: TTCCLL__OOKK This is the normal return code, and indicates that the command com- pleted successfully. The string gives the command's return value. TTCCLL__EERRRROORR Indicates that an error occurred; the string gives a message describ- ing the error. In addition, the | global variable eerrrroorrIInnffoo will con- | tain human-readable information | describing which commands and pro- | cedures were being executed when | the error occurred, and the global | variable eerrrroorrCCooddee will contain | machine-readable details about the | error, if they are available. See | the section BUILT-IN VARIABLES | below for more information. TTCCLL__RREETTUURRNN Indicates that the rreettuurrnn command has been invoked, and that the current procedure (or top-level command or ssoouurrccee command) should Sprite v1.0 16 Tcl C Library Procedures Tcl return immediately. The string gives the return value for the pro- cedure or command. TTCCLL__BBRREEAAKK Indicates that the bbrreeaakk command has been invoked, so the innermost loop should abort immediately. The string should always be empty. TTCCLL__CCOONNTTIINNUUEE Indicates that the ccoonnttiinnuuee command has been invoked, so the innermost loop should go on to the next iteration. The string should always be empty. Tcl programmers do not normally need to think about return codes, since TCL_OK is almost always returned. If anything else is returned by a command, then the Tcl interpreter immediately stops processing commands and returns to its caller. If there are several nested invocations of the Tcl interpreter in progress, then each nested command will usu- ally return the error to its caller, until eventually the error is reported to the top-level application code. The application will then display the error message for the user. In a few cases, some commands will handle certain ``error'' conditions themselves and not return them upwards. For example, the ffoorr command checks for the TCL_BREAK code; if it occurs, then ffoorr stops executing the body of the loop and returns TCL_OK to its caller. The ffoorr command also handles TCL_CONTINUE codes and the procedure interpreter handles TCL_RETURN codes. The ccaattcchh command allows Tcl programs to catch errors and handle them without aborting command interpretation any further. PPRROOCCEEDDUURREESS Tcl allows you to extend the command interface by defining procedures. A Tcl procedure can be invoked just like any other Tcl command (it has a name and it receives one or more arguments). The only difference is that its body isn't a piece of C code linked into the program; it is a string con- taining one or more other Tcl commands. See the pprroocc com- mand for information on how to define procedures and what happens when they are invoked. VVAARRIIAABBLLEESS -- SSCCAALLAARRSS AANNDD AARRRRAAYYSS Tcl allows the definition of variables and the use of their | values either through $$-style variable substitution, the sseett | command, or a few other mechanisms. Variables need not be | declared: a new variable will automatically be created each | Sprite v1.0 17 Tcl C Library Procedures Tcl time a new variable name is used. | Tcl supports two types of variables: scalars and arrays. A | scalar variable has a single value, whereas an array vari- | able can have any number of elements, each with a name | (called its ``index'') and a value. Array indexes may be | arbitrary strings; they need not be numeric. Parentheses | are used refer to array elements in Tcl commands. For exam- | ple, the command | sseett xx((ffiirrsstt)) 4444 | will modify the element of xx whose index is ffiirrsstt so that | its new value is 4444. Two-dimensional arrays can be simu- | lated in Tcl by using indexes that contain multiple con- | catenated values. For example, the commands | sseett aa((22,,33)) 11 | sseett aa((33,,66)) 22 | set the elements of aa whose indexes are 22,,33 and 33,,66. | In general, array elements may be used anywhere in Tcl that | scalar variables may be used. If an array is defined with a | particular name, then there may not be a scalar variable | with the same name. Similarly, if there is a scalar vari- | able with a particular name then it is not possible to make | array references to the variable. To convert a scalar vari- | able to an array or vice versa, remove the existing variable | with the uunnsseett command. | The aarrrraayy command provides several features for dealing with | arrays, such as querying the names of all the elements of | the array and searching through the array one element at a | time. Variables may be either global or local. If a variable name is used when a procedure isn't being executed, then it automatically refers to a global variable. Variable names used within a procedure normally refer to local variables associated with that invocation of the procedure. Local variables are deleted whenever a procedure exits. The gglloo-- bbaall command may be used to request that a name refer to a global variable for the duration of the current procedure (this is somewhat analogous to eexxtteerrnn in C). BBUUIILLTT--IINN CCOOMMMMAANNDDSS The Tcl library provides the following built-in commands, which will be available in any application using Tcl. In addition to these built-in commands, there may be additional commands defined by each application, plus commands defined as Tcl procedures. In the command syntax descriptions below, words in boldface are literals that you type verbatim Sprite v1.0 18 Tcl C Library Procedures Tcl to Tcl. Words in italics are meta-symbols; they serve as names for any of a range of values that you can type. Optional arguments or groups of arguments are indicated by enclosing them in question-marks. Ellipses (``...'') indi- cate that any number of additional arguments or groups of arguments may appear, in the same format as the preceding argument(s). aappppeenndd _v_a_r_N_a_m_e _v_a_l_u_e ?_v_a_l_u_e _v_a_l_u_e ...? Append all of the _v_a_l_u_e arguments to the current value | of variable _v_a_r_N_a_m_e. If _v_a_r_N_a_m_e doesn't exist, it is | given a value equal to the concatenation of all the | _v_a_l_u_e arguments. This command provides an efficient | way to build up long variables incrementally. For | example, ``aappppeenndd aa $$bb'' is much more efficient than | ``sseett aa $$aa$$bb'' if $$aa is long. aarrrraayy _o_p_t_i_o_n _a_r_r_a_y_N_a_m_e ?_a_r_g _a_r_g ...? This command performs one of several operations on the | variable given by _a_r_r_a_y_N_a_m_e. _A_r_r_a_y_N_a_m_e must be the | name of an existing array variable. The _o_p_t_i_o_n argu- | ment determines what action is carried out by the com- | mand. The legal _o_p_t_i_o_n_s (which may be abbreviated) | are: | aarrrraayy aannyymmoorree _a_r_r_a_y_N_a_m_e _s_e_a_r_c_h_I_d || Returns 1 if there are any more elements left to | be processed in an array search, 0 if all elements | have already been returned. _S_e_a_r_c_h_I_d indicates | which search on _a_r_r_a_y_N_a_m_e to check, and must have | been the return value from a previous invocation | of aarrrraayy ssttaarrttsseeaarrcchh. This option is particularly | useful if an array has an element with an empty | name, since the return value from aarrrraayy nneexxtteellee-- | mmeenntt won't indicate whether the search has been | completed. | aarrrraayy ddoonneesseeaarrcchh _a_r_r_a_y_N_a_m_e _s_e_a_r_c_h_I_d || This command terminates an array search and des- | troys all the state associated with that search. | _S_e_a_r_c_h_I_d indicates which search on _a_r_r_a_y_N_a_m_e to | destroy, and must have been the return value from | a previous invocation of aarrrraayy ssttaarrttsseeaarrcchh. | Returns an empty string. | aarrrraayy nnaammeess _a_r_r_a_y_N_a_m_e || Returns a list containing the names of all of the | elements in the array. If there are no elements | in the array then an empty string is returned. | aarrrraayy nneexxtteelleemmeenntt _a_r_r_a_y_N_a_m_e _s_e_a_r_c_h_I_d || Returns the name of the next element in _a_r_r_a_y_N_a_m_e, | Sprite v1.0 19 Tcl C Library Procedures Tcl or an empty string if all elements of _a_r_r_a_y_N_a_m_e | have already been returned in this search. The | _s_e_a_r_c_h_I_d argument identifies the search, and must | have been the return value of an aarrrraayy ssttaarrttsseeaarrcchh | command. Warning: if elements are added to or | deleted from the array, then all searches are | automatically terminated just as if aarrrraayy | ddoonneesseeaarrcchh had been invoked; this will cause aarrrraayy | nneexxtteelleemmeenntt operations to fail for those searches. | aarrrraayy ssiizzee _a_r_r_a_y_N_a_m_e || Returns a decimal string giving the number of ele- | ments in the array. | aarrrraayy ssttaarrttsseeaarrcchh _a_r_r_a_y_N_a_m_e || This command initializes an element-by-element | search through the array given by _a_r_r_a_y_N_a_m_e, such | that invocations of the aarrrraayy nneexxtteelleemmeenntt command | will return the names of the individual elements | in the array. When the search has been completed, | the aarrrraayy ddoonneesseeaarrcchh command should be invoked. | The return value is a search identifier that must | be used in aarrrraayy nneexxtteelleemmeenntt and aarrrraayy ddoonneesseeaarrcchh | commands; it allows multiple searches to be under- | way simultaneously for the same array. bbrreeaakk This command may be invoked only inside the body of a loop command such as ffoorr or ffoorreeaacchh or wwhhiillee. It returns a TCL_BREAK code to signal the innermost con- taining loop command to return immediately. ccaassee _s_t_r_i_n_g ?iinn? _p_a_t_L_i_s_t _b_o_d_y ?_p_a_t_L_i_s_t _b_o_d_y ...? ccaassee _s_t_r_i_n_g ?iinn? {_p_a_t_L_i_s_t _b_o_d_y ?_p_a_t_L_i_s_t _b_o_d_y ...?} Match _s_t_r_i_n_g against each of the _p_a_t_L_i_s_t arguments in order. If one matches, then evaluate the following _b_o_d_y argument by passing it recursively to the Tcl interpreter, and return the result of that evaluation. Each _p_a_t_L_i_s_t argument consists of a single pattern or list of patterns. Each pattern may contain any of the wild-cards described under ssttrriinngg mmaattcchh. If a _p_a_t_L_i_s_t argument is ddeeffaauulltt, the corresponding body will be evaluated if no _p_a_t_L_i_s_t matches _s_t_r_i_n_g. If no _p_a_t_L_i_s_t argument matches _s_t_r_i_n_g and no default is given, then the ccaassee command returns an empty string. Two syntaxes are provided. The first uses a separate argument for each of the patterns and commands; this form is convenient if substitutions are desired on some of the patterns or commands. The second form places | all of the patterns and commands together into a single | Sprite v1.0 20 Tcl C Library Procedures Tcl argument; the argument must have proper list structure, | with the elements of the list being the patterns and | commands. The second form makes it easy to construct | multi-line case commands, since the braces around the | whole list make it unnecessary to include a backslash | at the end of each line. Since the _p_a_t_L_i_s_t arguments | are in braces in the second form, no command or vari- | able substitutions are performed on them; this makes | the behavior of the second form different than the | first form in some cases. | Below are some examples of ccaassee commands: | ccaassee aabbcc iinn {{aa bb}} {{ffoorrmmaatt 11}} ddeeffaauulltt {{ffoorrmmaatt 22}} aa** {{ffoorrmmaatt 33}}| will return 33, | ccaassee aa iinn {{ | {{aa bb}} {{ffoorrmmaatt 11}} | ddeeffaauulltt {{ffoorrmmaatt 22}} | aa** {{ffoorrmmaatt 33}} | }} | will return 11, and | ccaassee xxyyzz {{ | {{aa bb}} | {{ffoorrmmaatt 11}} | ddeeffaauulltt | {{ffoorrmmaatt 22}} | aa** | {{ffoorrmmaatt 33}} | }} | will return 22. ccaattcchh _c_o_m_m_a_n_d ?_v_a_r_N_a_m_e? The ccaattcchh command may be used to prevent errors from aborting command interpretation. CCaattcchh calls the Tcl interpreter recursively to execute _c_o_m_m_a_n_d, and always returns a TCL_OK code, regardless of any errors that might occur while executing _c_o_m_m_a_n_d. The return value from ccaattcchh is a decimal string giving the code returned by the Tcl interpreter after executing _c_o_m_m_a_n_d. This will be 00 (TCL_OK) if there were no errors in _c_o_m_m_a_n_d; otherwise it will have a non-zero value corresponding to one of the exceptional return codes (see tcl.h for the definitions of code values). If the _v_a_r_N_a_m_e argu- ment is given, then it gives the name of a variable; ccaattcchh will set the value of the variable to the string returned from _c_o_m_m_a_n_d (either a result or an error mes- sage). ccdd ?_d_i_r_N_a_m_e? Change the current working directory to _d_i_r_N_a_m_e, or to | Sprite v1.0 21 Tcl C Library Procedures Tcl the home directory (as specified in the HOME environ- | ment variable) if _d_i_r_N_a_m_e is not given. If _d_i_r_N_a_m_e | starts with a tilde, then tilde-expansion is done as | described for TTccll__TTiillddeeSSuubbsstt. Returns an empty string. | This command can potentially be disruptive to an appli- | cation, so it may be removed in some applications. | cclloossee _f_i_l_e_I_d || Closes the file given by _f_i_l_e_I_d. _F_i_l_e_I_d must be the | return value from a previous invocation of the ooppeenn | command; after this command, it should not be used | anymore. If _f_i_l_e_I_d refers to a command pipeline | instead of a file, then cclloossee waits for the children to | complete. The normal result of this command is an | empty string, but errors are returned if there are | problems in closing the file or waiting for children to | complete. ccoonnccaatt _a_r_g ?_a_r_g ...? This command treats each argument as a list and con- catenates them into a single list. It permits any number of arguments. For example, the command ccoonnccaatt aa bb {{cc dd ee}} {{ff {{gg hh}}}} will return aa bb cc dd ee ff {{gg hh}} as its result. ccoonnttiinnuuee This command may be invoked only inside the body of a loop command such as ffoorr or ffoorreeaacchh or wwhhiillee. It returns a TCL_CONTINUE code to signal the innermost containing loop command to skip the remainder of the loop's body but continue with the next iteration of the loop. eeooff _f_i_l_e_I_d Returns 1 if an end-of-file condition has occurred on | _f_i_l_e_I_d, 0 otherwise. _F_i_l_e_I_d must have been the return | value from a previous call to ooppeenn, or it may be ssttddiinn, | ssttddoouutt, or ssttddeerrrr to refer to one of the standard I/O | channels. eerrrroorr _m_e_s_s_a_g_e ?_i_n_f_o? ?_c_o_d_e? Returns a TCL_ERROR code, which causes command interpretation to be unwound. _M_e_s_s_a_g_e is a string that is returned to the application to indicate what went wrong. If the _i_n_f_o argument is provided and is non-empty, it is used to initialize the global variable eerrrroorrIInnffoo. Sprite v1.0 22 Tcl C Library Procedures Tcl eerrrroorrIInnffoo is used to accumulate a stack trace of what was in progress when an error occurred; as nested com- mands unwind, the Tcl interpreter adds information to eerrrroorrIInnffoo. If the _i_n_f_o argument is present, it is used to initialize eerrrroorrIInnffoo and the first increment of unwind information will not be added by the Tcl inter- preter. In other words, the command containing the eerrrroorr command will not appear in eerrrroorrIInnffoo; in its place will be _i_n_f_o. This feature is most useful in conjunction with the ccaattcchh command: if a caught error cannot be handled successfully, _i_n_f_o can be used to return a stack trace reflecting the original point of occurrence of the error: ccaattcchh {{......}} eerrrrMMssgg sseett ssaavveeddIInnffoo $$eerrrroorrIInnffoo ...... eerrrroorr $$eerrrrMMssgg $$ssaavveeddIInnffoo If the _c_o_d_e argument is present, then its value is | stored in the eerrrroorrCCooddee global variable. This variable | is intended to hold a machine-readable description of | the error in cases where such information is available; | see the section BUILT-IN VARIABLES below for informa- | tion on the proper format for the variable. If the | _c_o_d_e argument is not present, then eerrrroorrCCooddee is | automatically reset to ``NONE'' by the Tcl interpreter | as part of processing the error generated by the com- | mand. eevvaall _a_r_g ?_a_r_g ...? EEvvaall takes one or more arguments, which together comprise a Tcl command (or collection of Tcl commands separated by newlines in the usual way). EEvvaall con- catenates all its arguments in the same fashion as the ccoonnccaatt command, passes the concatenated string to the Tcl interpreter recursively, and returns the result of that evaluation (or any error generated by it). eexxeecc _a_r_g ?_a_r_g ...? This command treats its arguments as the specification | of one or more UNIX commands to execute as sub- | processes. The commands take the form of a standard | shell pipeline; ``|'' arguments separate commands in | the pipeline and cause standard output of the preceding | command to be piped into standard input of the next | command. | Under normal conditions the result of the eexxeecc command | consists of the standard output produced by the last | command in the pipeline. If any of the commands in the | pipeline exit abnormally or are killed or suspended, | Sprite v1.0 23 Tcl C Library Procedures Tcl then eexxeecc will return an error and the error message | will include the pipeline's output followed by error | messages describing the abnormal terminations; the | eerrrroorrCCooddee variable will contain additional information | about the last abnormal termination encountered. If | any of the commands writes to its standard error file, | then eexxeecc will return an error, and the error message | will include the pipeline's output, followed by mes- | sages about abnormal terminations (if any), followed by | the standard error output. | If the last character of the result or error message is | a newline then that character is deleted from the | result or error message for consistency with normal Tcl | return values. | If an _a_r_g has the value ``>'' then the following argu- | ment is taken as the name of a file and the standard | output of the last command in the pipeline is | redirected to the file. In this situation eexxeecc will | normally return an empty string. | If an _a_r_g has the value ``<'' then the following argu- | ment is taken as the name of a file to use for standard | input to the first command in the pipeline. If an | argument has the value ``<<'' then the following argu- | ment is taken as an immediate value to be passed to the | first command as standard input. If there is no ``<'' | or ``<<'' argument then the standard input for the | first command in the pipeline is taken from the | application's current standard input. | If the last _a_r_g is ``&'' then the command will be exe- | cuted in background. In this case the standard output | from the last command in the pipeline will go to the | application's standard output unless redirected in the | command, and error output from all the commands in the | pipeline will go to the application's standard error | file. | Each _a_r_g becomes one word for a command, except for | ``|'', ``<'', ``<<'', ``>'', and ``&'' arguments, and | the arguments that follow ``<'', ``<<'', and ``>''. | The first word in each command is taken as the command | name; tilde-substitution is performed on it, and the | directories in the PATH environment variable are | searched for an executable by the given name. No | ``glob'' expansion or other shell-like substitutions | are performed on the arguments to commands. | eexxiitt ?returnCode? || Terminate the process, returning _r_e_t_u_r_n_C_o_d_e to the | Sprite v1.0 24 Tcl C Library Procedures Tcl parent as the exit status. If _r_e_t_u_r_n_C_o_d_e isn't speci- | fied then it defaults to 0. eexxpprr _a_r_g Calls the expression processor to evaluate _a_r_g, and returns the result as a string. See the section EXPRESSIONS above. ffiillee _o_p_t_i_o_n _n_a_m_e ?_a_r_g _a_r_g ...? Operate on a file or a file name. _N_a_m_e is the name of | a file; if it starts with a tilde, then tilde substitu- | tion is done before executing the command (see the | manual entry for TTccll__TTiillddeeSSuubbsstt for details). _O_p_t_i_o_n | indicates what to do with the file name. Any unique | abbreviation for _o_p_t_i_o_n is acceptable. The valid | options are: | ffiillee aattiimmee _n_a_m_e || Return a decimal string giving the time at which | file _n_a_m_e was last accessed. The time is measured | in the standard UNIX fashion as seconds from a | fixed starting time (often January 1, 1970). If | the file doesn't exist or its access time cannot | be queried then an error is generated. | ffiillee ddiirrnnaammee _n_a_m_e || Return all of the characters in _n_a_m_e up to but not | including the last slash character. If there are | no slashes in _n_a_m_e then return ``.''. If the last | slash in _n_a_m_e is its first character, then return | ``/''. | ffiillee eexxeeccuuttaabbllee _n_a_m_e || Return 11 if file _n_a_m_e is executable by the current | user, 00 otherwise. | ffiillee eexxiissttss _n_a_m_e || Return 11 if file _n_a_m_e exists and the current user | has search privileges for the directories leading | to it, 00 otherwise. | ffiillee eexxtteennssiioonn _n_a_m_e || Return all of the characters in _n_a_m_e after and | including the last dot in _n_a_m_e. If there is no | dot in _n_a_m_e then return the empty string. | ffiillee iissddiirreeccttoorryy _n_a_m_e || Return 11 if file _n_a_m_e is a directory, 00 otherwise. | ffiillee iissffiillee _n_a_m_e || Return 11 if file _n_a_m_e is a regular file, 00 other- | wise. | Sprite v1.0 25 Tcl C Library Procedures Tcl ffiillee llssttaatt _n_a_m_e _v_a_r_N_a_m_e || Same as ssttaatt option (see below) except uses the | _l_s_t_a_t kernel call instead of _s_t_a_t. This means | that if _n_a_m_e refers to a symbolic link the infor- | mation returned in _v_a_r_N_a_m_e is for the link rather | than the file it refers to. On systems that don't | support symbolic links this option behaves exactly | the same as the ssttaatt option. | ffiillee mmttiimmee _n_a_m_e || Return a decimal string giving the time at which | file _n_a_m_e was last modified. The time is measured | in the standard UNIX fashion as seconds from a | fixed starting time (often January 1, 1970). If | the file doesn't exist or its modified time cannot | be queried then an error is generated. | ffiillee oowwnneedd _n_a_m_e || Return 11 if file _n_a_m_e is owned by the current | user, 00 otherwise. | ffiillee rreeaaddaabbllee _n_a_m_e || Return 11 if file _n_a_m_e is readable by the current | user, 00 otherwise. | ffiillee rreeaaddlliinnkk _n_a_m_e || Returns the value of the symbolic link given by | _n_a_m_e (i.e. the name of the file it points to). If | _n_a_m_e isn't a symbolic link or its value cannot be | read, then an error is returned. On systems that | don't support symbolic links this option is unde- | fined. | ffiillee rroooottnnaammee _n_a_m_e || Return all of the characters in _n_a_m_e up to but not | including the last ``.'' character in the name. | If _n_a_m_e doesn't contain a dot, then return _n_a_m_e. | ffiillee ssiizzee _n_a_m_e || Return a decimal string giving the size of file | _n_a_m_e in bytes. If the file doesn't exist or its | size cannot be queried then an error is generated. | ffiillee ssttaatt _n_a_m_e _v_a_r_N_a_m_e || Invoke the ssttaatt kernel call on _n_a_m_e, and use the | variable given by _v_a_r_N_a_m_e to hold information | returned from the kernel call. _V_a_r_N_a_m_e is treated | as an array variable, and the following elements | of that variable are set: aattiimmee, ccttiimmee, ddeevv, ggiidd, | iinnoo, mmooddee, mmttiimmee, nnlliinnkk, ssiizzee, ttyyppee, uuiidd. Each | element except ttyyppee is a decimal string with the | value of the corresponding field from the ssttaatt | Sprite v1.0 26 Tcl C Library Procedures Tcl return structure; see the manual entry for ssttaatt | for details on the meanings of the values. The | ttyyppee element gives the type of the file in the | same form returned by the command ffiillee ttyyppee. This | command returns an empty string. | ffiillee ttaaiill _n_a_m_e || Return all of the characters in _n_a_m_e after the | last slash. If _n_a_m_e contains no slashes then | return _n_a_m_e. | ffiillee ttyyppee _n_a_m_e || Returns a string giving the type of file _n_a_m_e, | which will be one of ffiillee, ddiirreeccttoorryy, cchhaarraacc-- | tteerrSSppeecciiaall, bblloocckkSSppeecciiaall, ffiiffoo, lliinnkk, or ssoocckkeett. | ffiillee wwrriittaabbllee _n_a_m_e || Return 11 if file _n_a_m_e is writable by the current | user, 00 otherwise. | || The ffiillee commands that return 0/1 results are often | used in conditional or looping commands, for example: | iiff {{!![[ffiillee eexxiissttss ffoooo]]}} tthheenn {{eerrrroorr {{bbaadd ffiillee nnaammee}}}} eellssee {{......}}| fflluusshh _f_i_l_e_I_d Flushes any output that has been buffered for _f_i_l_e_I_d. | _F_i_l_e_I_d must have been the return value from a previous | call to ooppeenn, or it may be ssttddoouutt or ssttddeerrrr to access | one of the standard I/O streams; it must refer to a | file that was opened for writing. This command returns | an empty string. ffoorr _s_t_a_r_t _t_e_s_t _n_e_x_t _b_o_d_y FFoorr is a looping command, similar in structure to the C ffoorr statement. The _s_t_a_r_t, _n_e_x_t, and _b_o_d_y arguments must be Tcl command strings, and _t_e_s_t is an expression string. The ffoorr command first invokes the Tcl inter- preter to execute _s_t_a_r_t. Then it repeatedly evaluates _t_e_s_t as an expression; if the result is non-zero it invokes the Tcl interpreter on _b_o_d_y, then invokes the Tcl interpreter on _n_e_x_t, then repeats the loop. The command terminates when _t_e_s_t evaluates to 0. If a ccoonn-- ttiinnuuee command is invoked within _b_o_d_y then any remaining commands in the current execution of _b_o_d_y are skipped; processing continues by invoking the Tcl interpreter on _n_e_x_t, then evaluating _t_e_s_t, and so on. If a bbrreeaakk com- mand is invoked within _b_o_d_y or _n_e_x_t, then the ffoorr com- mand will return immediately. The operation of bbrreeaakk and ccoonnttiinnuuee are similar to the corresponding state- ments in C. FFoorr returns an empty string. Sprite v1.0 27 Tcl C Library Procedures Tcl ffoorreeaacchh _v_a_r_n_a_m_e _l_i_s_t _b_o_d_y In this command, _v_a_r_n_a_m_e is the name of a variable, _l_i_s_t is a list of values to assign to _v_a_r_n_a_m_e, and _b_o_d_y is a collection of Tcl commands. For each field in _l_i_s_t (in order from left to right), ffoorreeaacchh assigns the contents of the field to _v_a_r_n_a_m_e (as if the lliinnddeexx com- mand had been used to extract the field), then calls the Tcl interpreter to execute _b_o_d_y. The bbrreeaakk and ccoonnttiinnuuee statements may be invoked inside _b_o_d_y, with the same effect as in the ffoorr command. FFoorreeaacchh returns an empty string. ffoorrmmaatt _f_o_r_m_a_t_S_t_r_i_n_g ?_a_r_g _a_r_g ...? This command generates a formatted string in the same way as the C sspprriinnttff procedure (it uses sspprriinnttff in its implementation). _F_o_r_m_a_t_S_t_r_i_n_g indicates how to format the result, using %% fields as in sspprriinnttff, and the addi- tional arguments, if any, provide values to be substi- tuted into the result. All of the sspprriinnttff options are valid; see the sspprriinnttff man page for details. Each _a_r_g must match the expected type from the %% field in _f_o_r_- _m_a_t_S_t_r_i_n_g; the ffoorrmmaatt command converts each argument to the correct type (floating, integer, etc.) before pass- ing it to sspprriinnttff for formatting. The only unusual conversion is for %%cc; in this case the argument must be a decimal string, which will then be converted to the corresponding ASCII character value. FFoorrmmaatt does backslash substitution on its _f_o_r_m_a_t_S_t_r_i_n_g argument, so backslash sequences in _f_o_r_m_a_t_S_t_r_i_n_g will be handled correctly even if the argument is in braces. The return value from ffoorrmmaatt is the formatted string. ggeettss _f_i_l_e_I_d ?_v_a_r_N_a_m_e? Reads the next line from the file given by _f_i_l_e_I_d and | discards the terminating newline character. If _v_a_r_N_a_m_e | is specified, then the line is placed in the variable | by that name and the return value is a count of the | number of characters read (not including the newline). | If the end of the file is reached before reading any | characters then -1 is returned and _v_a_r_N_a_m_e is set to an | empty string. If _v_a_r_N_a_m_e is not specified then the | return value will be the line (minus the newline char- | acter) or an empty string if the end of the file is | reached before reading any characters. An empty string | will also be returned if a line contains no characters | except the newline, so eeooff may have to be used to | determine what really happened. If the last character | in the file is not a newline character, then ggeettss | behaves as if there were an additional newline charac- | ter at the end of the file. _F_i_l_e_I_d must be ssttddiinn or | the return value from a previous call to ooppeenn; it must | refer to a file that was opened for reading. Sprite v1.0 28 Tcl C Library Procedures Tcl gglloobb ?--nnooccoommppllaaiinn? _f_i_l_e_n_a_m_e ?_f_i_l_e_n_a_m_e ...? This command performs filename globbing, using csh rules. The returned value from gglloobb is the list of expanded filenames. If --nnooccoommppllaaiinn is specified as the | first argument then an empty list may be returned; | otherwise an error is returned if the expanded list is | empty. The --nnooccoommppllaaiinn argument must be provided | exactly: an abbreviation will not be accepted. gglloobbaall _v_a_r_n_a_m_e ?_v_a_r_n_a_m_e ...? This command is ignored unless a Tcl procedure is being interpreted. If so, then it declares the given _v_a_r_n_a_m_e's to be global variables rather than local ones. For the duration of the current procedure (and only while executing in the current procedure), any reference to any of the _v_a_r_n_a_m_es will be bound to a global variable instead of a local one. hhiissttoorryy ?_o_p_t_i_o_n? ?_a_r_g _a_r_g ...? Note: this command may not be available in all Tcl- based applications. Typically, only those that receive command input in a typescript form will support his- tory. The hhiissttoorryy command performs one of several operations related to recently-executed commands recorded in a history list. Each of these recorded commands is referred to as an ``event''. When specify- ing an event to the hhiissttoorryy command, the following forms may be used: [1] A number: if positive, it refers to the event with that number (all events are numbered starting at 1). If the number is negative, it selects an event relative to the current event (--11 refers to the previous event, --22 to the one before that, and so on). [2] A string: selects the most recent event that matches the string. An event is considered to match the string either if the string is the same as the first characters of the event, or if the string matches the event in the sense of the ssttrriinngg mmaattcchh command. The hhiissttoorryy command can take any of the following forms: hhiissttoorryy Same as hhiissttoorryy iinnffoo, described below. | hhiissttoorryy aadddd _c_o_m_m_a_n_d ?eexxeecc? Add the _c_o_m_m_a_n_d argument to the history list as a new event. If eexxeecc is specified (or abbreviated) Sprite v1.0 29 Tcl C Library Procedures Tcl then the command is also executed and its result is returned. If eexxeecc isn't specified then an empty string is returned as result. hhiissttoorryy cchhaannggee _n_e_w_V_a_l_u_e ?_e_v_e_n_t? Replace the value recorded for an event with _n_e_w_V_a_l_u_e. _E_v_e_n_t specifies the event to replace, and defaults to the _c_u_r_r_e_n_t event (not event --11). This command is intended for use in commands that implement new forms of history substitution and wish to replace the current event (which invokes the substitution) with the command created through substitution. The return value is an empty string. hhiissttoorryy eevveenntt ?_e_v_e_n_t? Returns the value of the event given by _e_v_e_n_t. _E_v_e_n_t defaults to --11. This command causes history revision to occur: see below for details. hhiissttoorryy iinnffoo ?_c_o_u_n_t? Returns a formatted string (intended for humans to read) giving the event number and contents for each of the events in the history list except the current event. If _c_o_u_n_t is specified then only the most recent _c_o_u_n_t events are returned. hhiissttoorryy kkeeeepp _c_o_u_n_t This command may be used to change the size of the history list to _c_o_u_n_t events. Initially, 20 events are retained in the history list. This command returns an empty string. hhiissttoorryy nneexxttiidd Returns the number of the next event to be recorded in the history list. It is useful for things like printing the event number in command- line prompts. hhiissttoorryy rreeddoo ?_e_v_e_n_t? Re-execute the command indicated by _e_v_e_n_t and return its result. _E_v_e_n_t defaults to --11. This command results in history revision: see below for details. hhiissttoorryy ssuubbssttiittuuttee _o_l_d _n_e_w ?_e_v_e_n_t? Retrieve the command given by _e_v_e_n_t (--11 by default), replace any occurrences of _o_l_d by _n_e_w in the command (only simple character equality is supported; no wild cards), execute the resulting command, and return the result of that execution. This command results in history revision: see Sprite v1.0 30 Tcl C Library Procedures Tcl below for details. hhiissttoorryy wwoorrddss _s_e_l_e_c_t_o_r ?_e_v_e_n_t? Retrieve from the command given by _e_v_e_n_t (--11 by default) the words given by _s_e_l_e_c_t_o_r, and return those words in a string separated by spaces. The sseelleeccttoorr argument has three forms. If it is a single number then it selects the word given by that number (00 for the command name, 11 for its first argument, and so on). If it consists of two numbers separated by a dash, then it selects all the arguments between those two. Otherwise sseelleecc-- ttoorr is treated as a pattern; all words matching that pattern (in the sense of ssttrriinngg mmaattcchh) are returned. In the numeric forms $$ may be used to select the last word of a command. For example, suppose the most recent command in the history list is ffoorrmmaatt {{%%ss iiss %%dd yyeeaarrss oolldd}} AAlliiccee [[eexxpprr $$aaggeeIInnMMoonntthhss//1122]] Below are some history commands and the results they would produce: Command_______ Result______ hhiissttoorryy wwoorrddss $$ [[eexxpprr $$aaggeeIInnMMoonntthhss//1122]] hhiissttoorryy wwoorrddss 11--22{{%%ss iiss %%dd yyeeaarrss oolldd}} AAlliiccee hhiissttoorryy wwoorrddss **aa**oo**{{%%ss iiss %%dd yyeeaarrss oolldd}} [[eexxpprr $$aaggeeIInnMMoonntthhss//1122]] HHiissttoorryy wwoorrddss results in history revision: see below for details. The history options eevveenntt, rreeddoo, ssuubbssttiittuuttee, and wwoorrddss result in ``history revision''. When one of these options is invoked then the current event is modified to eliminate the history command and replace it with the result of the history command. For example, sup- pose that the most recent command in the history list is sseett aa [[eexxpprr $$bb++22]] and suppose that the next command invoked is one of the ones on the left side of the table below. The command actually recorded in the history event will be the corresponding one on the right side of the table. Command Typed_____________ Command Recorded________________ hhiissttoorryy sseett aa [[eexxpprr $$bb++22]] hhiissttoorryy ss aa bb sseett bb [[eexxpprr $$bb++22]] sseett cc [[hhiissttoorryy ww 22]]sseett cc [[eexxpprr $$bb++22]] History revision is needed because event specifiers | like --11 are only valid at a particular time: once more | events have been added to the history list a different | Sprite v1.0 31 Tcl C Library Procedures Tcl event specifier would be needed. History revision | occurs even when hhiissttoorryy is invoked indirectly from the | current event (e.g. a user types a command that invokes | a Tcl procedure that invokes hhiissttoorryy): the top-level | command whose execution eventually resulted in a hhiiss-- | ttoorryy command is replaced. If you wish to invoke com- | mands like hhiissttoorryy wwoorrddss without history revision, you | can use hhiissttoorryy eevveenntt to save the current history event | and then use hhiissttoorryy cchhaannggee to restore it later. iiff _t_e_s_t ?tthheenn? _t_r_u_e_B_o_d_y ?eellssee? ?_f_a_l_s_e_B_o_d_y? The _i_f command evaluates _t_e_s_t as an expression (in the same way that eexxpprr evaluates its argument). The value of the expression must be numeric; if it is non-zero then _t_r_u_e_B_o_d_y is called by passing it to the Tcl inter- preter. Otherwise _f_a_l_s_e_B_o_d_y is executed by passing it to the Tcl interpreter. The tthheenn and eellssee arguments are optional ``noise words'' to make the command easier to read. _F_a_l_s_e_B_o_d_y is also optional; if it isn't specified then the command does nothing if _t_e_s_t evalu- ates to zero. The return value from iiff is the value of the last command executed in _t_r_u_e_B_o_d_y or _f_a_l_s_e_B_o_d_y, or the empty string if _t_e_s_t evaluates to zero and _f_a_l_s_e_- _B_o_d_y isn't specified. iinnccrr _v_a_r_N_a_m_e ?_i_n_c_r_e_m_e_n_t? Increment the value stored in the variable whose name | is _v_a_r_N_a_m_e. The value of the variable must be | integral. If _i_n_c_r_e_m_e_n_t is supplied then its value | (which must be an integer) is added to the value of | variable _v_a_r_N_a_m_e; otherwise 1 is added to _v_a_r_N_a_m_e. | The new value is stored as a decimal string in variable | _v_a_r_N_a_m_e and also returned as result. iinnffoo _o_p_t_i_o_n ?_a_r_g _a_r_g ...? Provide information about various internals to the Tcl interpreter. The legal _o_p_t_i_o_n's (which may be abbrevi- ated) are: iinnffoo aarrggss _p_r_o_c_n_a_m_e Returns a list containing the names of the argu- ments to procedure _p_r_o_c_n_a_m_e, in order. _P_r_o_c_n_a_m_e must be the name of a Tcl command procedure. iinnffoo bbooddyy _p_r_o_c_n_a_m_e Returns the body of procedure _p_r_o_c_n_a_m_e. _P_r_o_c_n_a_m_e must be the name of a Tcl command procedure. iinnffoo ccmmddccoouunntt Returns a count of the total number of commands that have been invoked in this interpreter. Sprite v1.0 32 Tcl C Library Procedures Tcl iinnffoo ccoommmmaannddss ?_p_a_t_t_e_r_n? If _p_a_t_t_e_r_n isn't specified, returns a list of names of all the Tcl commands, including both the built-in commands written in C and the command procedures defined using the pprroocc command. If _p_a_t_t_e_r_n is specified, only those names matching _p_a_t_t_e_r_n are returned. Matching is determined using the same rules as for ssttrriinngg mmaattcchh. iinnffoo ddeeffaauulltt _p_r_o_c_n_a_m_e _a_r_g _v_a_r_n_a_m_e _P_r_o_c_n_a_m_e must be the name of a Tcl command pro- cedure and _a_r_g must be the name of an argument to that procedure. If _a_r_g doesn't have a default value then the command returns 00. Otherwise it returns 11 and places the default value of _a_r_g into variable _v_a_r_n_a_m_e. iinnffoo eexxiissttss _v_a_r_N_a_m_e Returns 11 if the variable named _v_a_r_N_a_m_e exists in the current context (either as a global or local variable), returns 00 otherwise. iinnffoo gglloobbaallss ?_p_a_t_t_e_r_n? If _p_a_t_t_e_r_n isn't specified, returns a list of all the names of currently-defined global variables. If _p_a_t_t_e_r_n is specified, only those names matching _p_a_t_t_e_r_n are returned. Matching is determined using the same rules as for ssttrriinngg mmaattcchh. iinnffoo lleevveell ?_n_u_m_b_e_r? If _n_u_m_b_e_r is not specified, this command returns a number giving the stack level of the invoking pro- cedure, or 0 if the command is invoked at top- level. If _n_u_m_b_e_r is specified, then the result is a list consisting of the name and arguments for the procedure call at level _n_u_m_b_e_r on the stack. If _n_u_m_b_e_r is positive then it selects a particular stack level (1 refers to the top-most active pro- cedure, 2 to the procedure it called, and so on); otherwise it gives a level relative to the current level (0 refers to the current procedure, -1 to its caller, and so on). See the uupplleevveell command for more information on what stack levels mean. iinnffoo lliibbrraarryy Returns the name of the library directory in which | standard Tcl scripts are stored. If there is no | such directory defined for the current installa- | tion then an error is generated. See the lliibbrraarryy | manual entry for details of the facilities pro- | vided by the Tcl script library. Normally each | application will have its own application-specific | Sprite v1.0 33 Tcl C Library Procedures Tcl script library in addition to the Tcl script | library; I suggest that each application set a | global variable with a name like $$_a_p_pLLiibbrraarryy | (where _a_p_p is the application's name) to hold the | location of that application's library directory. iinnffoo llooccaallss ?_p_a_t_t_e_r_n? If _p_a_t_t_e_r_n isn't specified, returns a list of all the names of currently-defined local variables, including arguments to the current procedure, if any. Variables defined with the gglloobbaall and uuppvvaarr | commands will not be returned. If _p_a_t_t_e_r_n is specified, only those names matching _p_a_t_t_e_r_n are returned. Matching is determined using the same rules as for ssttrriinngg mmaattcchh. iinnffoo pprrooccss ?_p_a_t_t_e_r_n? If _p_a_t_t_e_r_n isn't specified, returns a list of all the names of Tcl command procedures. If _p_a_t_t_e_r_n is specified, only those names matching _p_a_t_t_e_r_n are returned. Matching is determined using the same rules as for ssttrriinngg mmaattcchh. iinnffoo ssccrriipptt If a Tcl script file is currently being evaluated | (i.e. there is a call to TTccll__EEvvaallFFiillee active or | there is an active invocation of the ssoouurrccee com- | mand), then this command returns the name of the | innermost file being processed. Otherwise the | command returns an empty string. iinnffoo ttccllvveerrssiioonn Returns the version number for this version of Tcl in the form _x._y, where changes to _x represent major changes with probable incompatibilities and changes to _y represent small enhancements and bug fixes that retain backward compatibility. iinnffoo vvaarrss ?_p_a_t_t_e_r_n? If _p_a_t_t_e_r_n isn't specified, returns a list of all the names of currently-visible variables, includ- ing both locals and currently-visible globals. If _p_a_t_t_e_r_n is specified, only those names matching _p_a_t_t_e_r_n are returned. Matching is determined using the same rules as for ssttrriinngg mmaattcchh. jjooiinn _l_i_s_t ?_j_o_i_n_S_t_r_i_n_g? The _l_i_s_t argument must be a valid Tcl list. This com- | mand returns the string formed by joining all of the | elements of _l_i_s_t together with _j_o_i_n_S_t_r_i_n_g separating | each adjacent pair of elements. The _j_o_i_n_S_t_r_i_n_g argu- | ment defaults to a space character. Sprite v1.0 34 Tcl C Library Procedures Tcl llaappppeenndd _v_a_r_N_a_m_e _v_a_l_u_e ?_v_a_l_u_e _v_a_l_u_e ...? Treat the variable given by _v_a_r_N_a_m_e as a list and | append each of the _v_a_l_u_e arguments to that list as a | separate element, with spaces between elements. If | _v_a_r_N_a_m_e doesn't exist, it is created as a list with | elements given by the _v_a_l_u_e arguments. LLaappppeenndd is | similar to aappppeenndd except that the _v_a_l_u_es are appended | as list elements rather than raw text. This command | provides a relatively efficient way to build up large | lists. For example, ``llaappppeenndd aa $$bb'' is much more | efficient than ``sseett aa [[ccoonnccaatt $$aa [[lliisstt $$bb]]]]'' when $$aa | is long. | lliinnddeexx _l_i_s_t _i_n_d_e_x || Treats _l_i_s_t as a Tcl list and returns the _i_n_d_e_x'th ele- | ment from it (0 refers to the first element of the | list). In extracting the element, _l_i_n_d_e_x observes the | same rules concerning braces and quotes and backslashes | as the Tcl command interpreter; however, variable sub- | stitution and command substitution do not occur. If | _i_n_d_e_x is negative or greater than or equal to the | number of elements in _v_a_l_u_e, then an empty string is | returned. | lliinnsseerrtt _l_i_s_t _i_n_d_e_x _e_l_e_m_e_n_t ?_e_l_e_m_e_n_t _e_l_e_m_e_n_t ...? || This command produces a new list from _l_i_s_t by inserting | all of the _e_l_e_m_e_n_t arguments just before the _i_n_d_e_xth | element of _l_i_s_t. Each _e_l_e_m_e_n_t argument will become a | separate element of the new list. If _i_n_d_e_x is less | than or equal to zero, then the new elements are | inserted at the beginning of the list. If _i_n_d_e_x is | greater than or equal to the number of elements in the | list, then the new elements are appended to the list. lliisstt _a_r_g ?_a_r_g ...? This command returns a list comprised of all the _a_r_gs. Braces and backslashes get added as necessary, so that the iinnddeexx command may be used on the result to re- extract the original arguments, and also so that eevvaall may be used to execute the resulting list, with _a_r_g_1 comprising the command's name and the other _a_r_gs comprising its arguments. LLiisstt produces slightly dif- ferent results than ccoonnccaatt: ccoonnccaatt removes one level of grouping before forming the list, while lliisstt works directly from the original arguments. For example, the command lliisstt aa bb {{cc dd ee}} {{ff {{gg hh}}}} will return aa bb {{cc dd ee}} {{ff {{gg hh}}}} while ccoonnccaatt with the same arguments will return Sprite v1.0 35 Tcl C Library Procedures Tcl aa bb cc dd ee ff {{gg hh}} lllleennggtthh _l_i_s_t || Treats _l_i_s_t as a list and returns a decimal string giv- | ing the number of elements in it. | llrraannggee _l_i_s_t _f_i_r_s_t _l_a_s_t || _L_i_s_t must be a valid Tcl list. This command will | return a new list consisting of elements _f_i_r_s_t through | _l_a_s_t, inclusive. _L_a_s_t may be eenndd (or any abbreviation | of it) to refer to the last element of the list. If | _f_i_r_s_t is less than zero, it is treated as if it were | zero. If _l_a_s_t is greater than or equal to the number | of elements in the list, then it is treated as if it | were eenndd. If _f_i_r_s_t is greater than _l_a_s_t then an empty | string is returned. Note: ``llrraannggee _l_i_s_t _f_i_r_s_t _f_i_r_s_t'' | does not always produce the same result as ``lliinnddeexx | _l_i_s_t _f_i_r_s_t'' (although it often does for simple fields | that aren't enclosed in braces); it does, however, pro- | duce exactly the same results as ``lliisstt [[lliinnddeexx _l_i_s_t | _f_i_r_s_t]]'' | llrreeppllaaccee _l_i_s_t _f_i_r_s_t _l_a_s_t ?_e_l_e_m_e_n_t _e_l_e_m_e_n_t ...? || Returns a new list formed by replacing one or more ele- | ments of _l_i_s_t with the _e_l_e_m_e_n_t arguments. _F_i_r_s_t gives | the index in _l_i_s_t of the first element to be replaced. | If _f_i_r_s_t is less than zero then it refers to the first | element of _l_i_s_t; the element indicated by _f_i_r_s_t must | exist in the list. _L_a_s_t gives the index in _l_i_s_t of the | last element to be replaced; it must be greater than | or equal to _f_i_r_s_t. _L_a_s_t may be eenndd (or any abbrevia- | tion of it) to indicate that all elements between _f_i_r_s_t | and the end of the list should be replaced. The _e_l_e_- | _m_e_n_t arguments specify zero or more new arguments to be | added to the list in place of those that were deleted. | Each _e_l_e_m_e_n_t argument will become a separate element of | the list. If no _e_l_e_m_e_n_t arguments are specified, then | the elements between _f_i_r_s_t and _l_a_s_t are simply deleted. | llsseeaarrcchh _l_i_s_t _p_a_t_t_e_r_n || Search the elements of _l_i_s_t to see if one of them | matches _p_a_t_t_e_r_n. If so, the command returns the index | of the first matching element. If not, the command | returns --11. Pattern matching is done in the same way | as for the ssttrriinngg mmaattcchh command. | llssoorrtt _l_i_s_t || Sort the elements of _l_i_s_t, returning a new list in | sorted order. ASCII sorting is used, with the result | in increasing order. ooppeenn _f_i_l_e_N_a_m_e ?_a_c_c_e_s_s? Sprite v1.0 36 Tcl C Library Procedures Tcl Opens a file and returns an identifier that may be used | in future invocations of commands like rreeaadd, ppuuttss, and | cclloossee. _F_i_l_e_N_a_m_e gives the name of the file to open; if | it starts with a tilde then tilde substitution is per- | formed as described for TTccll__TTiillddeeSSuubbsstt. If the first | character of _f_i_l_e_N_a_m_e is ``|'' then the remaining char- | acters of _f_i_l_e_N_a_m_e are treated as a command pipeline to | invoke, in the same style as for eexxeecc. In this case, | the identifier returned by ooppeenn may be used to write to | the command's input pipe or read from its output pipe. | The _a_c_c_e_s_s argument indicates the way in which the file | (or command pipeline) is to be accessed. It may have | any of the following values: | rr || Open the file for reading only; the file must | already exist. | rr++ || Open the file for both reading and writing; the | file must already exist. | ww || Open the file for writing only. Truncate it if it | exists. If it doesn't exist, create a new file. | ww++ || Open the file for reading and writing. Truncate | it if it exists. If it doesn't exist, create a | new file. | aa || Open the file for writing only. The file must | already exist, and the file is positioned so that | new data is appended to the file. | aa++ || Open the file for reading and writing. The file | must already exist, and the initial access posi- | tion is set to the end of the file. | _A_c_c_e_s_s defaults to rr. If a file is opened for both | reading and writing, then sseeeekk must be invoked between | a read and a write, or vice versa (this restriction | does not apply to command pipelines opened with ooppeenn). | When _f_i_l_e_N_a_m_e specifies a command pipeline and a | write-only access is used, then standard output from | the pipeline is directed to the current standard output | unless overridden by the command. When _f_i_l_e_N_a_m_e speci- | fies a command pipeline and a read-only access is used, | then standard input from the pipeline is taken from the | current standard input unless overridden by the | Sprite v1.0 37 Tcl C Library Procedures Tcl command. | pprroocc _n_a_m_e _a_r_g_s _b_o_d_y The pprroocc command creates a new Tcl command procedure, _n_a_m_e, replacing any existing command there may have been by that name. Whenever the new command is invoked, the contents of _b_o_d_y will be executed by the Tcl interpreter. _A_r_g_s specifies the formal arguments to the procedure. It consists of a list, possibly empty, each of whose elements specifies one argument. Each argument specifier is also a list with either one or two fields. If there is only a single field in the specifier, then it is the name of the argument; if there are two fields, then the first is the argument name and the second is its default value. braces and backslashes may be used in the usual way to specify complex default values. When _n_a_m_e is invoked, a local variable will be created for each of the formal arguments to the procedure; its value will be the value of corresponding argument in the invoking command or the argument's default value. Arguments with default values need not be specified in a procedure invocation. However, there must be enough actual arguments for all the formal arguments that don't have defaults, and there must not be any extra actual arguments. There is one special case to permit procedures with variable numbers of arguments. If the last formal argument has the name aarrggss, then a call to the procedure may contain more actual arguments than the procedure has formals. In this case, all of the actual arguments starting at the one that would be assigned to aarrggss are combined into a list (as if the lliisstt command had been used); this combined value is assigned to the local variable aarrggss. When _b_o_d_y is being executed, variable names normally refer to local variables, which are created automati- cally when referenced and deleted when the procedure returns. One local variable is automatically created for each of the procedure's arguments. Global vari- ables can only be accessed by invoking the gglloobbaall com- mand. The pprroocc command returns the null string. When a pro- cedure is invoked, the procedure's return value is the value specified in a rreettuurrnn command. If the procedure doesn't execute an explicit rreettuurrnn, then its return value is the value of the last command executed in the procedure's body. If an error occurs while executing the procedure body, then the procedure-as-a-whole will return that same error. Sprite v1.0 38 Tcl C Library Procedures Tcl ppuuttss _f_i_l_e_I_d _s_t_r_i_n_g ?nnoonneewwlliinnee? Writes the characters given by _s_t_r_i_n_g to the file given | by _f_i_l_e_I_d. PPuuttss normally outputs a newline character | after _s_t_r_i_n_g, but this feature may be suppressed by | specifying the nnoonneewwlliinnee argument. Output to files is | buffered internally by Tcl; the fflluusshh command may be | used to force buffered characters to be output. _F_i_l_e_I_d | must have been the return value from a previous call to | ooppeenn, or it may be ssttddoouutt or ssttddeerrrr to refer to one of | the standard I/O channels; it must refer to a file that | was opened for writing. | ppwwdd || Returns the path name of the current working directory. | rreeaadd _f_i_l_e_I_d || rreeaadd _f_i_l_e_I_d nnoonneewwlliinnee || rreeaadd _f_i_l_e_I_d _n_u_m_B_y_t_e_s || In the first form, all of the remaining bytes are read | from the file given by _f_i_l_e_I_d; they are returned as the | result of the command. If nnoonneewwlliinnee is specified as an | additional argument, then the last character of the | file is discarded if it is a newline. In the third | form, the extra argument specifies how many bytes to | read; exactly this many bytes will be read and | returned, unless there are fewer than _n_u_m_B_y_t_e_s bytes | left in the file; in this case, all the remaining bytes | are returned. _F_i_l_e_I_d must be ssttddiinn or the return value | from a previous call to ooppeenn; it must refer to a file | that was opened for reading. | _s_u_b_M_a_t_c_h_- | _V_a_r ...? | | rreeggeexxpp ?--iinnddiicceess? ?--nnooccaassee? _e_x_p _s_t_r_i_n_g ?_m_a_t_c_h_V_a_r? ?_s_u_b_M_a_t_c_h_V_a_r || Determines whether the regular expression _e_x_p matches | part or all of _s_t_r_i_n_g and returns 1 if it does, 0 if it | doesn't. See REGULAR EXPRESSIONS above for complete | information on the syntax of _e_x_p and how it is matched | against _s_t_r_i_n_g. | If the --nnooccaassee switch is specified then upper-case | characters in _s_t_r_i_n_g are treated as lower case during | the matching process. The --nnooccaassee switch must be | specified before _e_x_p and may not be abbreviated. | If additional arguments are specified after _s_t_r_i_n_g then | they are treated as the names of variables to use to | return information about which part(s) of _s_t_r_i_n_g | matched _e_x_p. _M_a_t_c_h_V_a_r will be set to the range of | _s_t_r_i_n_g that matched all of _e_x_p. The first _s_u_b_M_a_t_c_h_V_a_r | Sprite v1.0 39 Tcl C Library Procedures Tcl will contain the characters in _s_t_r_i_n_g that matched the | leftmost parenthesized subexpression within _e_x_p, the | next _s_u_b_M_a_t_c_h_V_a_r will contain the characters that | matched the next parenthesized subexpression to the | right in _e_x_p, and so on. | Normally, _m_a_t_c_h_V_a_r and the _s_u_b_M_a_t_c_h_V_a_rs are set to hold | the matching characters from ssttrriinngg. However, if the | --iinnddiicceess switch is specified then each variable will | contain a list of two decimal strings giving the | indices in _s_t_r_i_n_g of the first and last characters in | the matching range of characters. The --iinnddiicceess switch | must be specified before the _e_x_p argument and may not | be abbreviated. | If there are more _s_u_b_M_a_t_c_h_V_a_r's than parenthesized | subexpressions within _e_x_p, or if a particular subex- | pression in _e_x_p doesn't match the string (e.g. because | it was in a portion of the expression that wasn't | matched), then the corresponding _s_u_b_M_a_t_c_h_V_a_r will be | set to ``--11 --11'' if --iinnddiicceess has been specified or to | an empty string otherwise. | rreeggssuubb ?--aallll? ?--nnooccaassee? _e_x_p _s_t_r_i_n_g _s_u_b_S_p_e_c _v_a_r_N_a_m_e || This command matches the regular expression _e_x_p against | _s_t_r_i_n_g using the rules described in REGULAR EXPRESSIONS | above. If there is no match, then the command returns | 0 and does nothing else. If there is a match, then the | command returns 1 and also copies _s_t_r_i_n_g to the vari- | able whose name is given by _v_a_r_N_a_m_e. When copying | _s_t_r_i_n_g, the portion of _s_t_r_i_n_g that matched _e_x_p is | replaced with _s_u_b_S_p_e_c. If _s_u_b_S_p_e_c contains a ``&'' or | ``\0'', then it is replaced in the substitution with | the portion of _s_t_r_i_n_g that matched _e_x_p. If _s_u_b_S_p_e_c | contains a ``\_n'', where _n is a digit between 1 and 9, | then it is replaced in the substitution with the por- | tion of _s_t_r_i_n_g that matched the _n-th parenthesized | subexpression of _e_x_p. Additional backslashes may be | used in _s_u_b_S_p_e_c to prevent special interpretation of | ``&'' or ``\0'' or ``\_n'' or backslash. The use of | backslashes in _s_u_b_S_p_e_c tends to interact badly with the | Tcl parser's use of backslashes, so it's generally | safest to enclose _s_u_b_S_p_e_c in braces if it includes | backslashes. If the --aallll argument is specified, then | all ranges in _s_t_r_i_n_g that match _e_x_p are found and sub- | stitution is performed for each of these ranges; oth- | erwise only the first matching range is found and sub- | stituted. If --aallll is specified, then ``&'' and ``\_n'' | sequences are handled for each substitution using the | information from the corresponding match. If the | --nnooccaassee argument is specified, then upper-case charac- | ters in _s_t_r_i_n_g are converted to lower-case before | Sprite v1.0 40 Tcl C Library Procedures Tcl matching against _e_x_p; however, substitutions specified | by _s_u_b_S_p_e_c use the original unconverted form of _s_t_r_i_n_g. | The --aallll and --nnooccaassee arguments must be specified | exactly: no abbreviations are permitted. rreennaammee _o_l_d_N_a_m_e _n_e_w_N_a_m_e Rename the command that used to be called _o_l_d_N_a_m_e so that it is now called _n_e_w_N_a_m_e. If _n_e_w_N_a_m_e is an empty string (e.g. {}) then _o_l_d_N_a_m_e is deleted. The rreennaammee command returns an empty string as result. rreettuurrnn ?_v_a_l_u_e? Return immediately from the current procedure (or top- level command or ssoouurrccee command), with _v_a_l_u_e as the return value. If _v_a_l_u_e is not specified, an empty string will be returned as result. ssccaann _s_t_r_i_n_g _f_o_r_m_a_t _v_a_r_n_a_m_e_1 ?_v_a_r_n_a_m_e_2 ...? This command parses fields from an input string in the same fashion as the C ssssccaannff procedure. _S_t_r_i_n_g gives the input to be parsed and _f_o_r_m_a_t indicates how to parse it, using %% fields as in ssssccaannff. All of the ssssccaannff options are valid; see the ssssccaannff man page for details. Each _v_a_r_n_a_m_e gives the name of a variable; when a field is scanned from _s_t_r_i_n_g, the result is con- verted back into a string and assigned to the corresponding _v_a_r_n_a_m_e. The only unusual conversion is for %%cc. For %%cc conversions a single character value is converted to a decimal string, which is then assigned to the corresponding _v_a_r_n_a_m_e; no field width may be | specified for this conversion. | sseeeekk _f_i_l_e_I_d _o_f_f_s_e_t ?_o_r_i_g_i_n? || Change the current access position for _f_i_l_e_I_d. The | _o_f_f_s_e_t and _o_r_i_g_i_n arguments specify the position at | which the next read or write will occur for _f_i_l_e_I_d. | _O_f_f_s_e_t must be a number (which may be negative) and | _o_r_i_g_i_n must be one of the following: | ssttaarrtt || The new access position will be _o_f_f_s_e_t bytes from | the start of the file. | ccuurrrreenntt || The new access position will be _o_f_f_s_e_t bytes from | the current access position; a negative _o_f_f_s_e_t | moves the access position backwards in the file. | eenndd || The new access position will be _o_f_f_s_e_t bytes from | the end of the file. A negative _o_f_f_s_e_t places the | access position before the end-of-file, and a | Sprite v1.0 41 Tcl C Library Procedures Tcl positive _o_f_f_s_e_t places the access position after | the end-of-file. | The _o_r_i_g_i_n argument defaults to ssttaarrtt. _F_i_l_e_I_d must | have been the return value from a previous call to | ooppeenn, or it may be ssttddiinn, ssttddoouutt, or ssttddeerrrr to refer to | one of the standard I/O channels. This command returns | an empty string. | sseett _v_a_r_n_a_m_e ?_v_a_l_u_e? Returns the value of variable _v_a_r_n_a_m_e. If _v_a_l_u_e is specified, then set the value of _v_a_r_n_a_m_e to _v_a_l_u_e, creating a new variable if one doesn't already exist, and return its value. If _v_a_r_N_a_m_e contains an open | parenthesis and ends with a close parenthesis, then it | refers to an array element: the characters before the | open parenthesis are the name of the array, and the | characters between the parentheses are the index within | the array. Otherwise _v_a_r_N_a_m_e refers to a scalar vari- | able. If no procedure is active, then _v_a_r_n_a_m_e refers to a global variable. If a procedure is active, then _v_a_r_n_a_m_e refers to a parameter or local variable of the procedure, unless the _g_l_o_b_a_l command has been invoked to declare _v_a_r_n_a_m_e to be global. ssoouurrccee _f_i_l_e_N_a_m_e Read file _f_i_l_e_N_a_m_e and pass the contents to the Tcl interpreter as a sequence of commands to execute in the normal fashion. The return value of ssoouurrccee is the return value of the last command executed from the file. If an error occurs in executing the contents of the file, then the ssoouurrccee command will return that error. If a rreettuurrnn command is invoked from within the file, the remainder of the file will be skipped and the ssoouurrccee command will return normally with the result from the rreettuurrnn command. If _f_i_l_e_N_a_m_e starts with a tilde, then it is tilde-substituted as described in the TTccll__TTiillddeeSSuubbsstt manual entry. sspplliitt _s_t_r_i_n_g ?_s_p_l_i_t_C_h_a_r_s? Returns a list created by splitting _s_t_r_i_n_g at each character that is in the _s_p_l_i_t_C_h_a_r_s argument. Each element of the result list will consist of the charac- ters from _s_t_r_i_n_g between instances of the characters in _s_p_l_i_t_C_h_a_r_s. Empty list elements will be generated if _s_t_r_i_n_g contains adjacent characters in _s_p_l_i_t_C_h_a_r_s, or if the first or last character of _s_t_r_i_n_g is in _s_p_l_i_t_C_h_a_r_s. If _s_p_l_i_t_C_h_a_r_s is an empty string then each character of _s_t_r_i_n_g becomes a separate element of the result list. _S_p_l_i_t_C_h_a_r_s defaults to the standard white-space characters. For example, Sprite v1.0 42 Tcl C Library Procedures Tcl sspplliitt ""ccoommpp..uunniixx..mmiisscc"" .. returns ""ccoommpp uunniixx mmiisscc"" and sspplliitt ""HHeelllloo wwoorrlldd"" {{}} returns ""HH ee ll ll oo {{ }} ww oo rr ll dd"". ssttrriinngg _o_p_t_i_o_n _a_r_g ?_a_r_g ...? Perform one of several string operations, depending on _o_p_t_i_o_n. The legal _o_p_t_i_o_ns (which may be abbreviated) are: ssttrriinngg ccoommppaarree _s_t_r_i_n_g_1 _s_t_r_i_n_g_2 Perform a character-by-character comparison of strings _s_t_r_i_n_g_1 and _s_t_r_i_n_g_2 in the same way as the C ssttrrccmmpp procedure. Return -1, 0, or 1, depending on whether _s_t_r_i_n_g_1 is lexicographically less than, equal to, or greater than _s_t_r_i_n_g_2. ssttrriinngg ffiirrsstt _s_t_r_i_n_g_1 _s_t_r_i_n_g_2 Search _s_t_r_i_n_g_2 for a sequence of characters that exactly match the characters in _s_t_r_i_n_g_1. If found, return the index of the first character in the first such match within _s_t_r_i_n_g_2. If not found, return -1. ssttrriinngg iinnddeexx _s_t_r_i_n_g _c_h_a_r_I_n_d_e_x || Returns the _c_h_a_r_I_n_d_e_x'th character of the _s_t_r_i_n_g | argument. A _c_h_a_r_I_n_d_e_x of 0 corresponds to the | first character of the string. If _c_h_a_r_I_n_d_e_x is | less than 0 or greater than or equal to the length | of the string then an empty string is returned. ssttrriinngg llaasstt _s_t_r_i_n_g_1 _s_t_r_i_n_g_2 Search _s_t_r_i_n_g_2 for a sequence of characters that exactly match the characters in _s_t_r_i_n_g_1. If found, return the index of the first character in the last such match within _s_t_r_i_n_g_2. If there is no match, then return -1. ssttrriinngg lleennggtthh _s_t_r_i_n_g || Returns a decimal string giving the number of | characters in _s_t_r_i_n_g. ssttrriinngg mmaattcchh _p_a_t_t_e_r_n _s_t_r_i_n_g See if _p_a_t_t_e_r_n matches _s_t_r_i_n_g; return 1 if it does, 0 if it doesn't. Matching is done in a fashion similar to that used by the C-shell. For the two strings to match, their contents must be identical except that the following special sequences may appear in _p_a_t_t_e_r_n: ** Matches any sequence of characters in Sprite v1.0 43 Tcl C Library Procedures Tcl _s_t_r_i_n_g, including a null string. ?? Matches any single character in _s_t_r_i_n_g. [[_c_h_a_r_s]] Matches any character in the set given by _c_h_a_r_s. If a sequence of the form _x--_y appears in _c_h_a_r_s, then any character between _x and _y, inclusive, will match. \\_x Matches the single character _x. This provides a way of avoiding the special interpretation of the characters **??[[]]\\ in _p_a_t_t_e_r_n. ssttrriinngg rraannggee _s_t_r_i_n_g _f_i_r_s_t _l_a_s_t || Returns a range of consecutive characters from | _s_t_r_i_n_g, starting with the character whose index is | _f_i_r_s_t and ending with the character whose index is | _l_a_s_t. An index of 0 refers to the first character | of the string. _L_a_s_t may be eenndd (or any abbrevia- | tion of it) to refer to the last character of the | string. If _f_i_r_s_t is less than zero then it is | treated as if it were zero, and if _l_a_s_t is greater | than or equal to the length of the string then it | is treated as if it were eenndd. If _f_i_r_s_t is greater | than _l_a_s_t then an empty string is returned. | ssttrriinngg ttoolloowweerr _s_t_r_i_n_g || Returns a value equal to _s_t_r_i_n_g except that all | upper case letters have been converted to lower | case. | ssttrriinngg ttoouuppppeerr _s_t_r_i_n_g || Returns a value equal to _s_t_r_i_n_g except that all | lower case letters have been converted to upper | case. | ssttrriinngg ttrriimm _s_t_r_i_n_g ?_c_h_a_r_s? || Returns a value equal to _s_t_r_i_n_g except that any | leading or trailing characters from the set given | by _c_h_a_r_s are removed. If _c_h_a_r_s is not specified | then white space is removed (spaces, tabs, new- | lines, and carriage returns). | ssttrriinngg ttrriimmlleefftt _s_t_r_i_n_g ?_c_h_a_r_s? || Returns a value equal to _s_t_r_i_n_g except that any | leading characters from the set given by _c_h_a_r_s are | removed. If _c_h_a_r_s is not specified then white | space is removed (spaces, tabs, newlines, and car- | riage returns). | ssttrriinngg ttrriimmrriigghhtt _s_t_r_i_n_g ?_c_h_a_r_s? || Sprite v1.0 44 Tcl C Library Procedures Tcl Returns a value equal to _s_t_r_i_n_g except that any | trailing characters from the set given by _c_h_a_r_s | are removed. If _c_h_a_r_s is not specified then white | space is removed (spaces, tabs, newlines, and car- | riage returns). | tteellll _f_i_l_e_I_d || Returns a decimal string giving the current access | position in _f_i_l_e_I_d. _F_i_l_e_I_d must have been the return | value from a previous call to ooppeenn, or it may be ssttddiinn, | ssttddoouutt, or ssttddeerrrr to refer to one of the standard I/O | channels. ttiimmee _c_o_m_m_a_n_d ?_c_o_u_n_t? This command will call the Tcl interpreter _c_o_u_n_t times to execute _c_o_m_m_a_n_d (or once if _c_o_u_n_t isn't specified). It will then return a string of the form 550033 mmiiccrroosseeccoonnddss ppeerr iitteerraattiioonn which indicates the average amount of time required per iteration, in microseconds. Time is measured in elapsed time, not CPU time. ttrraaccee _o_p_t_i_o_n ?_a_r_g _a_r_g ...? Cause Tcl commands to be executed whenever certain | operations are invoked. At present, only variable | tracing is implemented. The legal _o_p_t_i_o_n's (which may | be abbreviated) are: | ttrraaccee vvaarriiaabbllee _n_a_m_e _o_p_s _c_o_m_m_a_n_d || Arrange for _c_o_m_m_a_n_d to be executed whenever vari- | able _n_a_m_e is accessed in one of the ways given by | _o_p_s. _N_a_m_e may refer to a normal variable, an ele- | ment of an array, or to an array as a whole (i.e. | _n_a_m_e may be just the name of an array, with no | parenthesized index). If _n_a_m_e refers to a whole | array, then _c_o_m_m_a_n_d is invoked whenever any ele- | ment of the array is manipulated. | _O_p_s indicates which operations are of interest, | and consists of one or more of the following | letters: | rr || Invoke _c_o_m_m_a_n_d whenever the variable is | read. | ww || Invoke _c_o_m_m_a_n_d whenever the variable is | written. | uu || Sprite v1.0 45 Tcl C Library Procedures Tcl Invoke _c_o_m_m_a_n_d whenever the variable is | unset. Variables can be unset expli- | citly with the uunnsseett command, or impli- | citly when procedures return (all of | their local variables are unset). Vari- | ables are also unset when interpreters | are deleted, but traces will not be | invoked because there is no interpreter | in which to execute them. | When the trace triggers, three arguments are | appended to _c_o_m_m_a_n_d so that the actual command is | as follows: | _c_o_m_m_a_n_d _n_a_m_e_1 _n_a_m_e_2 _o_p | _N_a_m_e_1 and _n_a_m_e_2 give the name(s) for the variable | being accessed: if the variable is a scalar then | _n_a_m_e_1 gives the variable's name and _n_a_m_e_2 is an | empty string; if the variable is an array element | then _n_a_m_e_1 gives the name of the array and name2 | gives the index into the array; if an entire array | is being deleted and the trace was registered on | the overall array, rather than a single element, | then _n_a_m_e_1 gives the array name and _n_a_m_e_2 is an | empty string. _O_p indicates what operation is | being performed on the variable, and is one of rr, | ww, or uu as defined above. | _C_o_m_m_a_n_d executes in the same context as the code | that invoked the traced operation: if the vari- | able was accessed as part of a Tcl procedure, then | _c_o_m_m_a_n_d will have access to the same local vari- | ables as code in the procedure. This context may | be different than the context in which the trace | was created. If _c_o_m_m_a_n_d invokes a procedure | (which it normally does) then the procedure will | have to use uuppvvaarr or uupplleevveell if it wishes to | access the traced variable. Note also that _n_a_m_e_1 | may not necessarily be the same as the name used | to set the trace on the variable; differences can | occur if the access is made through a variable | defined with the uuppvvaarr command. | For read and write traces, _c_o_m_m_a_n_d can modify the | variable to affect the result of the traced opera- | tion. If _c_o_m_m_a_n_d modifies the value of a variable | during a read or write trace, then the new value | will be returned as the result of the traced | operation. The return value from _c_o_m_m_a_n_d is | ignored except that if it returns an error of any | sort then the traced operation is aborted with an | error message saying that the access was denied | Sprite v1.0 46 Tcl C Library Procedures Tcl (this mechanism can be used to implement read-only | variables, for example). For write traces, _c_o_m_- | _m_a_n_d is invoked after the variable's value has | been changed; it can write a new value into the | variable to override the original value specified | in the write operation. To implement read-only | variables, _c_o_m_m_a_n_d will have to restore the old | value of the variable. | While _c_o_m_m_a_n_d is executing during a read or write | trace, traces on the variable are temporarily dis- | abled. This means that reads and writes invoked | by _c_o_m_m_a_n_d will occur directly, without invoking | _c_o_m_m_a_n_d (or any other traces) again. | When an unset trace is invoked, the variable has | already been deleted: it will appear to be unde- | fined with no traces. If an unset occurs because | of a procedure return, then the trace will be | invoked in the variable context of the procedure | being returned to: the stack frame of the return- | ing procedure will no longer exist. Traces are | not disabled during unset traces, so if an unset | trace command creates a new trace and accesses the | variable, the trace will be invoked. | If there are multiple traces on a variable they | are invoked in order of creation, most-recent | first. If one trace returns an error, then no | further traces are invoked for the variable. If | an array element has a trace set, and there is | also a trace set on the array as a whole, the | trace on the overall array is invoked before the | one on the element. | Once created, the trace remains in effect either | until the trace is removed with the ttrraaccee vvddeelleettee | command described below, until the variable is | unset, or until the interpreter is deleted. | Unsetting an element of array will remove any | traces on that element, but will not remove traces | on the overall array. | This command returns an empty string. | ttrraaccee vvddeelleettee _n_a_m_e _o_p_s _c_o_m_m_a_n_d || If there is a trace set on variable _n_a_m_e with the | operations and command given by _o_p_s and _c_o_m_m_a_n_d, | then the trace is removed, so that _c_o_m_m_a_n_d will | never again be invoked. Returns an empty string. | ttrraaccee vviinnffoo _n_a_m_e || Sprite v1.0 47 Tcl C Library Procedures Tcl Returns a list containing one element for each | trace currently set on variable _n_a_m_e. Each ele- | ment of the list is itself a list containing two | elements, which are the _o_p_s and _c_o_m_m_a_n_d associated | with the trace. If _n_a_m_e doesn't exist or doesn't | have any traces set, then the result of the com- | mand will be an empty string. | uunnkknnoowwnn _c_m_d_N_a_m_e ?_a_r_g _a_r_g ...? || This command doesn't actually exist as part of Tcl, but | Tcl will invoke it if it does exist. If the Tcl inter- | preter encounters a command name for which there is not | a defined command, then Tcl checks for the existence of | a command named uunnkknnoowwnn. If there is no such command, | then the interpeter returns an error. If the uunnkknnoowwnn | command exists, then it is invoked with arguments con- | sisting of the fully-substituted name and arguments for | the original non-existent command. The uunnkknnoowwnn command | typically does things like searching through library | directories for a command procedure with the name | _c_m_d_N_a_m_e, or expanding abbreviated command names to | full-length, or automatically executing unknown com- | mands as UNIX sub-processes. In some cases (such as | expanding abbreviations) uunnkknnoowwnn will change the origi- | nal command slightly and then (re-)execute it. The | result of the uunnkknnoowwnn command is used as the result for | the original non-existent command. | uunnsseett _n_a_m_e ?_n_a_m_e _n_a_m_e ...? || Remove one or more variables. Each _n_a_m_e is a variable | name, specified in any of the ways acceptable to the | sseett command. If a _n_a_m_e refers to an element of an | array, then that element is removed without affecting | the rest of the array. If a _n_a_m_e consists of an array | name with no parenthesized index, then the entire array | is deleted. The uunnsseett command returns an empty string | as result. An error occurs if any of the variables | doesn't exist. uupplleevveell ?_l_e_v_e_l? _c_o_m_m_a_n_d ?_c_o_m_m_a_n_d ...? All of the _c_o_m_m_a_n_d arguments are concatenated as if they had been passed to ccoonnccaatt; the result is then evaluated in the variable context indicated by _l_e_v_e_l. UUpplleevveell returns the result of that evaluation. If _l_e_v_e_l is an integer, then it gives a distance (up the procedure calling stack) to move before executing the command. If _l_e_v_e_l consists of ## followed by a number then the number gives an absolute level number. If _l_e_v_e_l is omitted then it defaults to 11. _L_e_v_e_l cannot be defaulted if the first _c_o_m_m_a_n_d argument starts with a digit or ##. For example, suppose that procedure aa was invoked from top-level, and that it called bb, and Sprite v1.0 48 Tcl C Library Procedures Tcl that bb called cc. Suppose that cc invokes the uupplleevveell command. If _l_e_v_e_l is 11 or ##22 or omitted, then the command will be executed in the variable context of bb. If _l_e_v_e_l is 22 or ##11 then the command will be executed in the variable context of aa. If _l_e_v_e_l is 33 or ##00 then the command will be executed at top-level (only global variables will be visible). The uupplleevveell command causes the invoking procedure to disappear from the procedure calling stack while the command is being executed. In the above example, suppose cc invokes the command uupplleevveell 11 {{sseett xx 4433;; dd}} where dd is another Tcl procedure. The sseett command will modify the variable xx in bb's context, and dd will exe- cute at level 3, as if called from bb. If it in turn executes the command uupplleevveell {{sseett xx 4422}} then the sseett command will modify the same variable xx in bb's context: the procedure cc does not appear to be on the call stack when dd is executing. The command ``iinnffoo lleevveell'' may be used to obtain the level of the current procedure. UUpplleevveell makes it possible to implement new control constructs as Tcl procedures (for example, uupplleevveell could be used to implement the wwhhiillee construct as a Tcl procedure). uuppvvaarr ?_l_e_v_e_l? _o_t_h_e_r_V_a_r _m_y_V_a_r ?_o_t_h_e_r_V_a_r _m_y_V_a_r ...? This command arranges for one or more local variables | in the current procedure to refer to variables in an | enclosing procedure call or to global variables. _L_e_v_e_l | may have any of the forms permitted for the uupplleevveell | command, and may be omitted if the first letter of the | first _o_t_h_e_r_V_a_r isn't ## or a digit (it defaults to 11). | For each _o_t_h_e_r_V_a_r argument, uuppvvaarr makes the variable by | that name in the procedure frame given by _l_e_v_e_l (or at | global level, if _l_e_v_e_l is ##00) accessible in the current | procedure by the name given in the corresponding _m_y_V_a_r | argument. The variable named by _o_t_h_e_r_V_a_r need not | exist at the time of the call; it will be created the | first time _m_y_V_a_r is referenced, just like an ordinary | variable. UUppvvaarr may only be invoked from within pro- | cedures. Neither _o_t_h_e_r_V_a_r or _m_y_V_a_r may refer to an | element of an array. UUppvvaarr returns an empty string. | The uuppvvaarr command simplifies the implementation of | call-by-name procedure calling and also makes it easier | to build new control constructs as Tcl procedures. For | example, consider the following procedure: | pprroocc aadddd22 nnaammee {{ | uuppvvaarr $$nnaammee xx | Sprite v1.0 49 Tcl C Library Procedures Tcl sseett xx [[eexxpprr $$xx++22]] | }} | AAdddd22 is invoked with an argument giving the name of a | variable, and it adds two to the value of that vari- | able. Although aadddd22 could have been implemented using | uupplleevveell instead of uuppvvaarr, uuppvvaarr makes it simpler for | aadddd22 to access the variable in the caller's procedure | frame. wwhhiillee _t_e_s_t _b_o_d_y The _w_h_i_l_e command evaluates _t_e_s_t as an expression (in | the same way that eexxpprr evaluates its argument). The | value of the expression must be numeric; if it is non- | zero then _b_o_d_y is executed by passing it to the Tcl | interpreter. Once _b_o_d_y has been executed then _t_e_s_t is | evaluated again, and the process repeats until eventu- | ally _t_e_s_t evaluates to a zero numeric value. CCoonnttiinnuuee | commands may be executed inside _b_o_d_y to terminate the | current iteration of the loop, and bbrreeaakk commands may | be executed inside _b_o_d_y to cause immediate termination | of the wwhhiillee command. The wwhhiillee command always returns | an empty string. BBUUIILLTT--IINN VVAARRIIAABBLLEESS The following global variables are created and managed automatically by the Tcl library. Except where noted below, these variables should normally be treated as read-only by application-specific code and by users. eennvv This variable is maintained by Tcl as an array whose | elements are the environment variables for the process. | Reading an element will return the value of the | corresponding environment variable. Setting an element | of the array will modify the corresponding environment | variable or create a new one if it doesn't already | exist. Unsetting an element of eennvv will remove the | corresponding environment variable. Changes to the eennvv | array will affect the environment passed to children by | commands like eexxeecc. If the entire eennvv array is unset | then Tcl will stop monitoring eennvv accesses and will not | update environment variables. | eerrrroorr-- | CCooddee || After an error has occurred, this variable will be set | to hold additional information about the error in a | form that is easy to process with programs. eerrrroorrCCooddee | consists of a Tcl list with one or more elements. The | first element of the list identifies a general class of | errors, and determines the format of the rest of the | Sprite v1.0 50 Tcl C Library Procedures Tcl list. The following formats for eerrrroorrCCooddee are used by | the Tcl core; individual applications may define addi- | tional formats. | CCHHIILLDDKKIILLLLEEDD _p_i_d _s_i_g_N_a_m_e _m_s_g || This format is used when a child process has been | killed because of a signal. The second element of | eerrrroorrCCooddee will be the process's identifier (in | decimal). The third element will be the symbolic | name of the signal that caused the process to ter- | minate; it will be one of the names from the | include file signal.h, such as SSIIGGPPIIPPEE. The | fourth element will be a short human-readable mes- | sage describing the signal, such as ``write on | pipe with no readers'' for SSIIGGPPIIPPEE. | CCHHIILLDDSSTTAATTUUSS _p_i_d _c_o_d_e || This format is used when a child process has | exited with a non-zero exit status. The second | element of eerrrroorrCCooddee will be the process's iden- | tifier (in decimal) and the third element will be | the exit code returned by the process (also in | decimal). | CCHHIILLDDSSUUSSPP _p_i_d _c_o_d_e || This format is used when a child process has been | suspended because of a signal. The second element | of eerrrroorrCCooddee will be the process's identifier, in | decimal. The third element will be the symbolic | name of the signal that caused the process to | suspend; this will be one of the names from the | include file signal.h, such as SSIIGGTTTTIINN. The | fourth element will be a short human-readable mes- | sage describing the signal, such as ``background | tty read'' for SSIIGGTTTTIINN. | NNOONNEE || This format is used for errors where no additional | information is available for an error besides the | message returned with the error. In these cases | eerrrroorrCCooddee will consist of a list containing a sin- | gle element whose contents are NNOONNEE. | UUNNIIXX _e_r_r_N_a_m_e _m_s_g || If the first element of eerrrroorrCCooddee is UUNNIIXX, then | the error occurred during a UNIX kernel call. The | second element of the list will contain the sym- | bolic name of the error that occurred, such as | EENNOOEENNTT; this will be one of the values defined in | the include file errno.h. The third element of | the list will be a human-readable message | corresponding to _e_r_r_N_a_m_e, such as ``no such file | Sprite v1.0 51 Tcl C Library Procedures Tcl or directory'' for the EENNOOEENNTT case. | To set eerrrroorrCCooddee, applications should use library pro- | cedures such as TTccll__SSeettEErrrroorrCCooddee and TTccll__UUnniixxEErrrroorr, or | they may invoke the eerrrroorr command. If one of these | methods hasn't been used, then the Tcl interpreter will | reset the variable to NNOONNEE after the next error. | eerrrroorrIInnffoo After an error has occurred, this string will contain one or more lines identifying the Tcl commands and pro- cedures that were being executed when the most recent error occurred. Its contents take the form of a stack trace showing the various nested Tcl commands that had been invoked at the time of the error. AAUUTTHHOORR John Ousterhout, University of California at Berkeley (ouster@sprite.berkeley.edu) Many people have contributed to Tcl in various ways, but the following people have made unusually large contributions: Bill Carpenter Peter Da Silva Mark Diekhans Karl Lehenbauer Mary Ann May-Pumphrey Sprite v1.0 52